# sky-gin-server

**Repository Path**: sky-zhou_admin/sky-gin-server

## Basic Information

- **Project Name**: sky-gin-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: chery_project
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-04-21
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sky Gin Server

A metadata-driven backend framework built with Gin for rapid business application development. Sky Gin Server provides a flexible, database-configured routing and CRUD system that eliminates repetitive code and accelerates development.

## Features

- **Metadata-Driven Routing**: Routes are dynamically loaded from database configuration, eliminating hardcoded route definitions
- **Extensible Handler System**: Plugin-style handler registration with automatic dependency injection
- **Command Pattern Architecture**: Flexible business logic implementation through the Table Command pattern
- **Auto-Transaction Management**: Automatic transaction handling with commit/rollback based on handler results
- **Permission-Based Access Control**: Built-in authentication and authorization middleware
- **Multi-Tenancy Support**: Company-level data isolation through `SYS_COMPANY_ID`
- **Metadata-Driven UI**: Table and column metadata for dynamic frontend generation
- **Custom Actions**: Configurable buttons and actions (URL, JavaScript, stored procedures)

## Requirements

- Go 1.22.4 or higher
- MySQL 5.7+
- Redis
- Docker (optional, for containerized deployment)

## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/sky-xhsoft/sky-gin-server.git
cd sky-gin-server
```

### 2. Install Dependencies

```bash
go mod download
```

### 3. Database Setup

Create a MySQL database and import your schema. The system requires the following metadata tables:

- `sys_api`: Route definitions
- `sys_table`: Table metadata
- `sys_column`: Column metadata
- `sys_action`: Custom action definitions
- `sys_user`: User management
- `sys_route`: Menu/routing configuration
- `sys_dict`: Dictionary/lookup data

### 4. Configure the Application

Create a `config.yml` file in the project root (see Configuration section below).

## Configuration

The application uses YAML configuration files. Create `config.yml` for production or `config_dev.yml` for development:

```yaml
System:
  project:
    name: sky-gin-server
    lang: zh-ch
    head-login-token: Token
    head-sign-token: Authorization
    max-requests-per-second: 1000
    session-ttl: 24
  port: "0.0.0.0:9090"
  shareUrl: "http://your-domain.com/share/"

Mysql:
  dsn: "username:password@tcp(localhost:3306)/database?charset=utf8mb4&parseTime=true&loc=Local"

Redis:
  addr: localhost
  password: ""
  db: 0
  port: 6379

oss:
  endpoint: oss-cn-region.aliyuncs.com
  accessKeyId: YOUR_ACCESS_KEY_ID
  accessKeySecret: YOUR_ACCESS_KEY_SECRET
  bucketName: your-bucket
  baseUrl: your-bucket.oss-cn-region.aliyuncs.com
  region: cn-region

sms:
  accessKeyId: YOUR_ACCESS_KEY_ID
  accessKeySecret: YOUR_ACCESS_KEY_SECRET
  signName: Your-Sign-Name
  templateCode: SMS_TEMPLATE_CODE
```

### Environment-Specific Configuration

Use the `SKY_ENV` environment variable to load different configs:

```bash
# Loads config.yml (default)
go run cmd/api-server/sky-gin-server.go

# Loads config_dev.yml
SKY_ENV=dev go run cmd/api-server/sky-gin-server.go

# Loads config_prod.yml
SKY_ENV=prod go run cmd/api-server/sky-gin-server.go
```

## Running the Application

### Development Mode

```bash
# Default configuration
go run cmd/api-server/sky-gin-server.go

# With specific environment
SKY_ENV=dev go run cmd/api-server/sky-gin-server.go
```

### Production Build

```bash
# Build the binary
go build -o sky-server ./cmd/api-server/sky-gin-server.go

# Run the binary
./sky-server
```

### Docker Deployment

```bash
# Build Docker image
docker build -t sky-gin-server .

# Run container
docker run -p 9090:8080 \
  -v $(pwd)/config.yml:/app/config.yml \
  -v $(pwd)/logs:/app/logs \
  sky-gin-server
```

## Project Structure

```
sky-gin-server/
├── cmd/api-server/          # Application entry point
├── config/                  # Configuration management
├── core/                    # Core framework (FX modules, routing)
├── handlers/                # HTTP request handlers
│   ├── SysHandlers/        # System management handlers
│   ├── TableHandler/       # Generic table CRUD handlers
│   └── VideoHandlers/      # Business-specific handlers
├── middleware/              # Gin middleware components
├── models/                  # Database models (GORM)
├── pkg/                     # Shared utilities
│   ├── log/                # Logging utilities
│   ├── response/           # Response formatters
│   ├── token/              # JWT token handling
│   └── utils/              # Common utilities
├── routers/                 # Route registration
├── service/                 # Business logic layer
│   ├── TableCmdService/    # Command pattern implementations
│   └── QueryService/       # Query builders
├── store/                   # Database and cache initialization
└── static/                  # Static file serving
```

## Development Guide

### Adding a New Handler

1. Create a new handler file in the appropriate directory (e.g., `handlers/SysHandlers/MyHandler.go`)

2. Implement the `Handler` interface:

```go
package SysHandlers

import (
    "github.com/gin-gonic/gin"
    "github.com/sky-xhsoft/sky-gin-server/handlers"
)

func init() {
    handlers.Register("MyHandler", &MyHandler{})
}

type MyHandler struct {
    handlers.BaseHandler
}

func (h *MyHandler) HandlerName() string {
    return "MyHandler"
}

func (h *MyHandler) MyMethod(c *gin.Context) {
    tx := c.MustGet("TX").(*gorm.DB)
    // Your business logic here
}
```

3. Add route configuration to the `sys_api` table:

```sql
INSERT INTO sys_api (METHOD, PATH, HANDLE, PERMISSION, IS_ACTIVE)
VALUES ('POST', '/api/my-endpoint', 'MyHandler.MyMethod', 'S', 'Y');
```

### Adding a Table Command

1. Create a command service in `service/TableCmdService/`:

```go
package TableCmdService

import "github.com/sky-xhsoft/sky-gin-server/service"

func init() {
    service.RegisterTableCmd("MyCmdName", func() service.TableCmdService {
        return &MyCmdService{}
    })
}

type MyCmdService struct {
    service.CmdContext
}

func (s *MyCmdService) CmdName() string {
    return "MyCmdName"
}

func (s *MyCmdService) Execute() (map[string]interface{}, error) {
    // Your command logic here
    return map[string]interface{}{"success": true}, nil
}
```

### Permission Types

Routes in `sys_api` support three permission levels:

- **P (Public)**: No authentication required
- **S (Secure)**: Token authentication required
- **D (Data)**: Token authentication + data-level permissions (future feature)

### Transaction Handling

All handlers automatically receive a database transaction via the middleware. DO NOT manually begin/commit transactions:

```go
func (h *MyHandler) MyMethod(c *gin.Context) {
    // Get the auto-managed transaction
    tx := c.MustGet("TX").(*gorm.DB)

    // Use the transaction for all DB operations
    tx.Create(&model)

    // Add errors to trigger rollback
    if err != nil {
        c.Error(err)
        return
    }

    // Transaction auto-commits on success
}
```

## API Documentation

The system provides dynamic API documentation based on metadata. Access the API docs at:

```
GET /api/sys/api-doc
```

## Testing

```bash
# Run all tests
go test ./...

# Run tests with verbose output
go test -v ./...

# Run tests in a specific package
go test ./pkg/hash

# Run a specific test
go test -run TestHashPassword ./pkg/hash
```

## Health Check

The application provides a health check endpoint:

```
GET /ping
```

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Author

**xhsoftware-skyzhou**

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request