REST 接口规范

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的通用方法，定义以下标准方法：

三、UiSimpleQR 泛型参数约定

go

type Ui{业务模块}Request struct { basedto.BaseEntity uiframe.UiSimpleQR[*QueryRequest, *DbEntity, *ResultResponse] }

四、请求参数结构

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）

五、响应结构规范

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 路径

路径命名规则

• 使用小驼峰命名：/api/trainOnline/list
• 避免下划线：不推荐/api/train_online/list

七、错误码规范

八、代码实现示例

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 }

九、最佳实践

1. 统一响应格式: 所有接口返回统一的PageResult或IchubResult结构
2. 错误处理: 使用pagemodel.PageFail()和basedto.ResultFailUser()统一错误返回
3. 日志记录: 在失败路径记录错误日志golog.Error(ret)
4. 参数校验: 在initQuery()中完成参数校验和条件组装
5. 权限控制: 通过self.User判断用户角色和权限

此规范基于现有代码模式和UiSimpleQR接口设计，确保与项目架构保持一致。