1.搜索关键字字段

1.一个搜索框，搜索内容是多个（或者以后可能会扩展）：字段使用search 2.两个搜索框，一个搜索固定，一个搜索多个：固定使用指定搜索字段定义，搜索多个字段使用search 3.两个或多个搜索框，都为搜索多个：字段使用待确定

2.page和page_size定义

统一使用uint32类型，page和pagesize需要给定默认值，如下

// CheckPage 校验page
func CheckPage(page uint32) uint32 {
  if page == 0 {
    page = 1
  }
  return page
}

// CheckPageSize 校验page_size
func CheckPageSize(size uint32) (uint32, error) {
  if size == 0 {
    size = 30
  } else if size > 100 {
    return 0, errors.New("超过获取条数限制")
  }
  return size, nil
}

app如果有page和page_size字段，需要校验

req.Page = common.CheckPage(req.Page)
req.PageSize, err = common.CheckPageSize(req.PageSize)
if err != nil {
  return nil, common.ErrPageSizeOutOfLimit
}

接口返回字段也需要返回page和page_size的定义，因为如果前端不传page和page_size时，是会给个默认值的，为了防止前端页码计算错误，使用后端返回的page和page_size，需要把字段放在page_info里，已定义公共的page_info，具体使用方式如下：

// proto需要使用page_info的地方先import
import "application/basic/page.proto";


/** remark: 分页信息 */
basic.PageInfo page_info = 1;

3.接口请求方式是GET还是POST

常用的 HTTP 动词有下面两个（括号里是对应的 SQL 命令）。

  • GET（SELECT）：从服务器取出资源（一项或多项）。
  • POST（CREATE\UPDATE\DELETE）：在服务器新建\更新\删除一个资源。

特殊情况获取数据传参为数组的情况用POST

4.状态码

未登录的情况返回401的状态码

其他情况统一使用200

如果特殊情况，组内沟通再定。

5.时间戳字段

字段描述需要明确描述时间戳的格式，比如是秒级的时间戳还是毫秒级别的，需要给个示例

6.时间字段

非特殊情况，时间统一使用秒级别的时间戳（即不会有时区问题，查询时如果有索引检索的效率也很高）

7.接口返回的id应该是具体业务的id

例如： 用户的id不使用id，而应使用user_id

架构的id不使用id，而应使用depart_id

总结：避免使用id的情况，应该是具体业务表前缀带上id的形式 业务表_id

8.类型、状态值等使用enum定义

proto入参和出参返回的都是enum，使用的是字符串，为了enum值的简单明了，定义在message里，其他地方要用，引入message里的enum，例如

message DescribeEpsResponse {
  enum EpsStatus {
    /** remark: 企业状态类型未指定*/
    UNSPECIFIED = 0;

    /** remark: 试用*/
    TRY_OUT = 1;

    /** remark: 正式*/
    FORMAL = 2;

    /** remark: 删除*/
    DELETE = 3;

    /** remark: 到期*/
    FROZEN = 4;
  }
  /** remark: 机构ID */
  int64 eps_id = 1;

  /** remark: 机构名称 */
  string eps_name = 2;

  /** remark: 企业状态 TRY_OUT-试用 FORMAL-正式 DELETE-删除 FROZEN-到期 */
  EpsStatus status = 3;
}

// 其他message要使用这个enum
message TestMessage {
  /** remark: 企业状态 TRY_OUT-试用 FORMAL-正式 DELETE-删除 FROZEN-到期 */
  DescribeEpsResponse.EpsStatus status = 3;
}

9.接口命名规范

遵守腾讯的api接口规范：​​https://www.tapd.cn/38236375/markdown_wikis/show/#1138236375001001129​​

10.list数据返回字段统一叫rows

特殊情况如果接口返回多个list，可以是具体的含义，例如 只返回一个list

{
    "requestId": "537704154e3b3ac0",
    "code": "0",
    "msg": "success",
    "data": {
        "rows": [
            {
                "user_id": "1",
                "user_name": "用户1",                
            },
            {
                "user_id": "2",
                "user_name": "用户2",               
            },
            
        ]
    }
}

接口返回两个list

{
    "requestId": "537704154e3b3ac0",
    "code": "0",
    "msg": "success",
    "data": {
        "user_list": [
            {
                "user_id": "1",
                "user_name": "用户1",                
            },
            {
                "user_id": "2",
                "user_name": "用户2",               
            },
            
        ],
        "eps_list":[
           {
                "eps_id": "1",
                "eps_name": "企业1",                
            },
            {
                "eps_id": "2",
                "eps_name": "企业2",               
            },
        ]
    }
}

error_enum定义的错误返回信息使用句号结尾

var NotAddTask = getError(errdef.CodeError{
  ErrorCode:  "NotAddTask",
  ErrorMsg:   "该阶段中已经有学员进行学习，不可添加。",
  StatusCode: codes.AlreadyExists,
})