139 lines
4.2 KiB
Markdown
139 lines
4.2 KiB
Markdown
# Backend 新增 HTTP 接口流程（Go + Fiber + atomctl）
|
||
|
||
本文档描述在本仓库 `backend/` 中新增一个 HTTP 接口（例如 `/super/v1/...`）的标准流程，包含路由生成、Swagger 文档生成、参数绑定与测试验证。
|
||
|
||
## 相关目录
|
||
|
||
- 路由与 Controller：`backend/app/http/**`
|
||
- Super 端示例：`backend/app/http/super/*.go`
|
||
- 生成路由：`backend/app/http/super/routes.gen.go`（自动生成，勿手改）
|
||
- Swagger 文档：
|
||
- `backend/docs/swagger.yaml`
|
||
- `backend/docs/swagger.json`
|
||
- `backend/docs/docs.go`（自动生成，勿手改）
|
||
- 本地接口调试示例：`backend/super.http`
|
||
- 命令：`backend/Makefile`（`make init`/`make run`/`make test` 等）
|
||
|
||
## 增加一个新接口（推荐步骤）
|
||
|
||
### 1) 选择模块与 BasePath
|
||
|
||
- **Super 管理端**：一般挂在 `/super/v1/...`，代码放在 `backend/app/http/super/`。
|
||
- **租户端**：项目 `main.go` 注解里有 `@BasePath /t/{tenant_code}/v1`，通常租户端接口会以该前缀为基础（具体以现有路由模块为准）。
|
||
|
||
先决定：
|
||
|
||
- `METHOD`：GET/POST/PATCH/DELETE…
|
||
- `PATH`：例如 `/super/v1/users/{id}` 或 `/super/v1/users/:id`
|
||
- 鉴权：是否需要 token/权限（跟随模块现有中间件）
|
||
- 请求：path/query/body
|
||
- 响应：结构体 / 分页 / KV 列表等
|
||
|
||
### 2) 定义请求 DTO（Filter/Form）与响应 DTO
|
||
|
||
Super 模块常见模式：
|
||
|
||
- 列表分页：`dto.*Filter` / `dto.*PageFilter` + 返回 `requests.Pager`
|
||
- 更新类接口：`dto.*UpdateForm`（body）
|
||
- KV 枚举列表：返回 `[]requests.KV`
|
||
|
||
可参考：
|
||
|
||
- `backend/app/http/super/dto/*`
|
||
- `backend/app/http/super/user.go`、`backend/app/http/super/tenant.go`
|
||
|
||
### 3) 编写 Controller 方法（带 Swagger 注解 + Bind）
|
||
|
||
在对应模块的 `*.go` 中新增方法，保持和现有风格一致：
|
||
|
||
- Controller struct 上保留 `// @provider`
|
||
- 方法上补齐 swagger 注解：`@Summary/@Tags/@Param/@Success/@Router`
|
||
- 使用 `@Bind` 约定参数来源（path/query/body）
|
||
|
||
示例（参考 `backend/app/http/super/user.go`）：
|
||
|
||
```go
|
||
// @Summary 用户状态列表
|
||
// @Tags Super
|
||
// @Accept json
|
||
// @Produce json
|
||
// @Success 200 {array} requests.KV
|
||
// @Router /super/v1/users/statuses [get]
|
||
func (*user) statusList(ctx fiber.Ctx) ([]requests.KV, error) { ... }
|
||
```
|
||
|
||
注意：
|
||
|
||
- `@Router` 的路径写法通常与 Fiber 路由一致（例如 `:userID`）。
|
||
- 参数绑定会驱动路由代码生成（见下一步）。
|
||
|
||
### 4) 连接业务层（Service）
|
||
|
||
Controller 内尽量只做：
|
||
|
||
- 参数解析/校验
|
||
- 调用 `services.*` 完成业务
|
||
- 返回结果或 error
|
||
|
||
业务逻辑集中放在 `backend/app/services`（结合现有实现），涉及 DB 的部分走现有模型/仓储层（依项目既有组织）。
|
||
|
||
### 5) 生成路由代码（routes.gen.go）
|
||
|
||
本项目路由是由 `atomctl` 自动生成的。
|
||
|
||
常用命令（在 `backend/` 下执行）：
|
||
|
||
- 仅生成路由：`atomctl gen route`
|
||
- 全量初始化/更新（含 swagger/enum/route/service 等）：`make init`
|
||
|
||
生成完成后检查：
|
||
|
||
- `backend/app/http/<module>/routes.gen.go` 是否出现新路由
|
||
- 路由 METHOD/PATH、参数绑定是否正确
|
||
|
||
### 6) 生成 Swagger 文档（swagger.yaml/json/docs.go）
|
||
|
||
Swagger 也是由工具生成并落盘到 `backend/docs/`：
|
||
|
||
- `atomctl swag init`
|
||
- 或直接 `make init`（会包含该步骤）
|
||
|
||
生成完成后检查：
|
||
|
||
- `backend/docs/swagger.yaml`、`backend/docs/swagger.json` 是否包含新接口
|
||
- `backend/docs/docs.go` 是否同步更新
|
||
|
||
### 7) 本地验证
|
||
|
||
启动：
|
||
|
||
- `make run`（会先 `make build`）
|
||
|
||
验证方式：
|
||
|
||
- 使用 `backend/super.http` 增加/执行请求
|
||
- 或用 curl/Swagger UI（若项目已暴露 swagger 页面）
|
||
|
||
### 8) 增加测试（建议）
|
||
|
||
优先参考现有 e2e 测试：
|
||
|
||
- `backend/tests/e2e/*`
|
||
|
||
覆盖至少：
|
||
|
||
- 正常请求返回
|
||
- 参数缺失/非法
|
||
- 权限不足/未登录（如该接口需要鉴权）
|
||
|
||
运行：
|
||
|
||
- `make test`
|
||
|
||
## 常见注意事项
|
||
|
||
- 不要手改 `*.gen.go`、`backend/docs/docs.go`：它们由 `atomctl` 生成。
|
||
- 确认查询参数命名与 swagger 一致（例如 `page/limit/asc/desc/status`），前端会按 swagger 拼 query。
|
||
- 路由路径参数请在 `@Router` 与函数签名/`@Bind` 里保持一致（例如 `tenantID`、`userID`）。
|
||
|