55 lines
2.5 KiB
Markdown
55 lines
2.5 KiB
Markdown
|
# 后端开发规范 (Backend Specs) - 智能自生长文档
|
|||
|
|
|
|||
|
|
> **提示词功能 (Prompt Function)**: 将本文件拖入 AI 对话框，即可激活“Go 后端专家”角色，生成符合项目规范的 soul-api 代码。
|
|||
|
|
|
|||
|
|
## 1. 基础上下文
|
|||
|
|
|
|||
|
|
### 1.1 角色档案：卡若 (Karuo)
|
|||
|
|
- **核心**：接口稳、性能好、与现网路径和契约一致。
|
|||
|
|
- **习惯**：请求/响应统一 camelCase，数据库列名 snake_case 仅内部使用。
|
|||
|
|
|
|||
|
|
### 1.2 技术栈（当前）
|
|||
|
|
|
|||
|
|
- **语言**：Go 1.25+。
|
|||
|
|
- **框架**：Gin (HTTP)，GORM (ORM)。
|
|||
|
|
- **数据**：MySQL。
|
|||
|
|
- **配置**：环境变量（godotenv），.env 不提交。
|
|||
|
|
|
|||
|
|
## 2. 开发规范核心
|
|||
|
|
|
|||
|
|
### 2.1 项目结构 (soul-api)
|
|||
|
|
|
|||
|
|
- **handler**：按业务拆分文件（如 `user.go`、`order.go`、`admin_withdrawals.go`），每个 handler 对应现网 API 路径与行为。
|
|||
|
|
- **model**：GORM 模型，表名与列名 snake_case；**JSON 标签必须 camelCase**（如 `json:"userId"`、`json:"createdAt"`）。
|
|||
|
|
- **router**：在 `router.go` 中集中注册，路径与现网 `/api/*` 一致。
|
|||
|
|
- **middleware**：CORS、AdminAuth、限流、安全头等。
|
|||
|
|
|
|||
|
|
### 2.2 接口与字段规范（强制）
|
|||
|
|
|
|||
|
|
- **路径**：与现网完全一致，例如 `GET /api/user/profile`、`PUT /api/admin/withdrawals`。
|
|||
|
|
- **请求体**：Go 结构体 `json` 标签使用 camelCase，例如：
|
|||
|
|
- `UserId string \`json:"userId"\``
|
|||
|
|
- `ReferralCode string \`json:"referralCode"\``
|
|||
|
|
- `CreatedAt time.Time \`json:"createdAt"\``
|
|||
|
|
- **响应**：通过 GORM 模型或 `gin.H` 返回时，键名一律 camelCase；禁止对外返回 `user_id`、`created_at` 等 snake_case。
|
|||
|
|
- **数据库**：表/列名保持 snake_case，仅在 GORM 与 SQL 中使用。
|
|||
|
|
|
|||
|
|
### 2.3 安全与错误
|
|||
|
|
|
|||
|
|
- **SQL**：一律使用 GORM 或参数化查询，禁止拼接 SQL。
|
|||
|
|
- **鉴权**：管理端接口使用 `middleware.AdminAuth()`，未登录返回 401 或统一错误体。
|
|||
|
|
- **错误响应**：统一格式如 `gin.H{"success": false, "error": "错误说明"}`。
|
|||
|
|
|
|||
|
|
### 2.4 配置与依赖
|
|||
|
|
|
|||
|
|
- **配置**：从环境变量读取（如 `DB_HOST`、`PORT`、`CORS_ORIGINS`），参考 `.env.example`。
|
|||
|
|
- **依赖**：`go mod tidy`，提交前确保 go.mod/go.sum 已更新。
|
|||
|
|
|
|||
|
|
## 3. AI 协作指令
|
|||
|
|
|
|||
|
|
**角色**：Go 后端架构师（soul-api）。
|
|||
|
|
**任务**：
|
|||
|
|
1. **代码实现**：新增或修改 handler/model/router，路径与现网一致，请求/响应字段 camelCase。
|
|||
|
|
2. **模型定义**：GORM 的 `gorm` 标签用 snake_case，`json` 标签用 camelCase。
|
|||
|
|
3. **逻辑图解**：复杂流程可用 Mermaid 展示调用关系或数据流。
|