REST 接口规范
一、命名规范
1. 文件命名
- 规则: 小写字母 + 下划线（snake_case）
- 示例: ui_train_online_request.go
2. 结构体命名
- 请求结构体: {业务模块}Request
- 示例: TrainOnlineRequest, TrainPlanRequest
- 响应结构体: {业务模块}Result
- 示例: TrainOnlineResult, TrainPlanResp
- UI请求封装: Ui{业务模块}Request
- 示例: UiTrainOnlineRequest, UiTrainRequest
3. 字段命名
- JSON序列化: 小驼峰（camelCase）
- 数据库字段: 下划线命名（snake_case）
- 示例:
go
type TrainOnlineRequest struct {
StudentId int64 `json:"studentId,string" gorm:"column:student_id"`
TrainPlanId int64 `json:"trainPlanId,string" gorm:"column:train_plan_id"`
StudentName string `json:"studentName" gorm:"column:student_name"`
}
二、接口方法命名规范
基于 UiSimpleQR 的通用方法，定义以下标准方法：
| UiList() | 分页查询列表 | GET | /api/trainOnline/list |
| UiSave() | 新增保存 | POST | /api/trainOnline |
| UiUpdate() | 更新数据 | PUT | /api/trainOnline |
| UiDeleteByIdResult() | 按ID删除 | DELETE | /api/trainOnline/{id} |
| UiGetById() | 按ID查询 | GET | /api/trainOnline/{id} |
| Patch{Action}() | 局部更新（如签到、通知） | PATCH | /api/trainOnline/{id}/signIn |
三、UiSimpleQR 泛型参数约定
go
type Ui{业务模块}Request struct {
basedto.BaseEntity
uiframe.UiSimpleQR[*QueryRequest, *DbEntity, *ResultResponse]
}
| Q (第1位) | 查询请求体 | 如 *TrainOnlineRequest |
| E (第2位) | 数据库实体 | 如 *planentity.TrainOnline |
| R (第3位) | 响应结果 | 如 *TrainOnlineResult |
四、请求参数结构
1. 查询参数（Query）
go
type TrainOnlineRequest struct {
// 基础字段
Id int64 `json:"id,string"`
StudentId int64 `json:"studentId,string"`
TrainPlanId int64 `json:"trainPlanId,string"`
// 模糊查询字段
UserNo string `json:"userNo"`
StudentName string `json:"studentName"`
Phone string `json:"phone"`
// 枚举/状态字段
TrainMode int32 `json:"trainMode"`
TrainType int32 `json:"trainType"`
Status []int16 `json:"status"`
// 时间范围
DateRange *dateutils.DateRange `json:"dateRange"`
}
2. 分页参数（继承自 SimpleParam）
| pageCurrent | int | 当前页码 | 1 |
| pageSize | int | 每页大小 | 10 |
| orderBys | string | 排序字段 | 如 startAt|desc |
| keyword | string | 通用搜索关键字 | – |
五、响应结构规范
1. 分页响应
go
type PageResult[R any] struct {
Code int `json:"code"` // 状态码
Msg string `json:"msg"` // 提示信息
Total int64 `json:"total"` // 总记录数
Data []*R `json:"data"` // 数据列表
}
2. 操作响应
go
type IchubResult struct {
Code int `json:"code"` // 0成功，非0失败
Msg string `json:"msg"` // 提示信息
}
3. 单条数据响应
go
type TrainOnlineResult struct {
simplemodel.Model `json:"model"` // 基础模型字段
StudentId int64 `json:"studentId,string"`
TrainPlanId int64 `json:"trainPlanId,string"`
StudentName string `json:"studentName"`
// … 其他业务字段
// 关联实体
Actual planentity.Actual `json:"actual"`
TrainSign planentity.TrainSign `json:"trainSign"`
CoachOn planentity.CoachOn `json:"coach"`
}
六、接口路径规范
标准 CRUD 路径
| 列表查询 | GET | /api/{module}/list | 分页查询 |
| 单条查询 | GET | /api/{module}/{id} | 按ID查询 |
| 新增 | POST | /api/{module} | 新增数据 |
| 更新 | PUT | /api/{module}/{id} | 更新数据 |
| 删除 | DELETE | /api/{module}/{id} | 删除数据 |
| 批量删除 | DELETE | /api/{module}/batch | 批量删除 |
| 局部更新 | PATCH | /api/{module}/{id}/{action} | 如签到、通知 |
路径命名规则
- 使用小驼峰命名：/api/trainOnline/list
- 避免下划线：不推荐 /api/train_online/list
七、错误码规范
| 200 | 成功 | 操作成功 |
| -1 | 参数错误 | 请求参数校验失败 |
| -2 | 用户不存在 | 用户未登录或不存在 |
| -3 | 权限不足 | 无操作权限 |
| -4 | 数据不存在 | 查询/操作的数据不存在 |
| -5 | 业务错误 | 业务逻辑校验失败 |
八、代码实现示例
1. UI请求结构体定义
go
type UiTrainOnlineRequest struct {
basedto.BaseEntity
uiframe.UiSimpleQR[*TrainOnlineRequest, *planentity.TrainOnline, *TrainOnlineResult]
}
func NewUiTrainOnlineRequest() *UiTrainOnlineRequest {
var req = &UiTrainOnlineRequest{}
req.InitDao()
req.initQuery()
return req
}
2. 查询初始化
go
func (self *UiTrainOnlineRequest) initQuery() *UiTrainOnlineRequest {
self.SetBeforeQuery(func() {
self.BuildGeneralParams(self.PageDbRequest)
self.DbEq("opc_id", self.GetOpcId())
// 业务条件
if self.Query.StudentId > 0 {
self.DbEq("student_id", self.Query.StudentId)
}
if self.Query.TrainPlanNo != "" {
self.DbLike("train_plan_no", self.Query.TrainPlanNo)
}
})
return self
}
3. 标准方法实现
go
func (self *UiTrainOnlineRequest) UiList() *pagemodel.PageResult[*TrainOnlineResult] {
// 前置校验
if self.GetUserId() == 0 {
return pagemodel.PageFail[*TrainOnlineResult]("用户不存在")
}
// 执行查询并转换
var ret = self.PageTo(self.List())
// 数据填充
for i := range ret.Data {
// 关联数据填充逻辑
}
return ret
}
九、最佳实践
此规范基于现有代码模式和 UiSimpleQR 接口设计，确保与项目架构保持一致。
