设计接口时，先把契约说清楚

请求要明确

先说明字段的含义、类型、是否必填，以及空值代表什么。对于分页，约定页码从 0 还是 1 开始；对于时间，明确时区与格式。

下面只是一个响应结构示例，具体字段应按项目契约确定。

json

{
  "items": [{ "id": "example-1", "title": "第一条记录" }],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

错误响应应让调用方知道发生了什么，以及下一步可以做什么。区分参数错误、认证失败、权限不足、资源不存在和服务异常。

不要只检查 HTTP 状态，也要遵循项目约定的业务成功条件。错误提示可以给用户看，日志则应保留足够的排查信息，同时避免写入密码和令牌。