假设需要为校园招聘信息发布系统设计一套API接口标准，请说明如何定义接口的请求参数、响应结构、错误码，并解释选择这些设计的原因。

成都理工大学就业指导中心标准专员（飞行部）难度：中等

答案

1) 【一句话结论】：采用RESTful架构设计API，通过HTTP方法语义区分操作（GET/POST等）、分类请求参数（路径/查询/请求体）、标准化响应结构（状态码+数据/错误体）及细粒度错误码体系，结合URL版本管理，确保接口可维护、易扩展，符合校园招聘系统的高效与稳定需求。

2) 【原理/概念讲解】：首先，HTTP方法语义：GET用于查询（幂等、可缓存），POST用于创建（非幂等、不可缓存），PUT用于更新（幂等、不可缓存），DELETE用于删除（幂等、不可缓存）。参数类型选择：路径参数（唯一标识，如职位ID，用GET/PUT/DELETE，需验证唯一性），查询参数（可选筛选，如部门、页码，用GET，无唯一性，需处理默认值），请求体（核心数据，如职位详情，用POST/PUT，需验证完整性）。响应结构：所有响应包含HTTP状态码（200成功，4xx/5xx错误），成功返回data（业务数据），错误返回code（错误码）、message（描述）、data（错误详情）。错误码：遵循HTTP标准（4xx客户端，5xx服务器），自定义细粒度（如4001参数缺失，4002格式错误），确保标准化。

3) 【对比与适用场景】：

参数类型	定义	特性	使用场景	注意点
路径参数	URL路径中的占位符（如`/jobs/{id}`）	传递唯一资源标识，必须提供，GET/PUT/DELETE方法	获取（GET）、更新（PUT）、删除（DELETE）特定资源（如查询ID为1的职位）	需验证唯一性，不能为空，GET方法幂等
查询参数	URL后的问号参数（如`?department=计算机&page=1`）	传递可选筛选条件，无唯一性，GET方法	分页（page, size）、筛选（status, department）、排序（sort）	可为空，需处理默认值，GET方法可缓存
请求体	请求正文（JSON/FormData）	传递创建/更新资源的完整数据，POST/PUT方法	创建新职位（POST /jobs）、更新职位信息（PUT /jobs/{id}）	需验证数据完整性，敏感数据加密

响应情况	状态码	响应体内容	设计原因
成功（列表）	200	`{"code":200,"message":"查询成功","data":{"total":50,"page":1,"size":10,"jobs":[]}`	明确业务数据，客户端解析简单
参数错误（如department为空）	400	`{"code":4001,"message":"参数 'department' 不能为空","data":{"invalidParams":["department"]}}`	标准化错误，客户端统一处理
服务器错误（数据库连接失败）	500	`{"code":5001,"message":"服务器内部错误","data":null}`	遵循HTTP 5xx，区分客户端/服务器错误

4) 【示例】：以“查询职位列表”API（GET /api/v1/jobs?department=计算机&page=1&size=10）为例：

请求：GET /api/v1/jobs?department=计算机&page=1&size=10

响应（成功，200）：

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "total": 50,
    "page": 1,
    "size": 10,
    "jobs": [
      {"id":1,"title":"Java开发工程师","department":"计算机","description":"负责系统开发...","status":"active"}
    ]
  }
}

以“创建新职位”API（POST /api/v1/jobs）为例：

请求：POST /api/v1/jobs，请求体：

{
  "title": "Python工程师",
  "department": "计算机",
  "description": "负责后端开发",
  "status": "active",
  "salary": "15k"
}

响应（成功，201 Created）：

{
  "code": 201,
  "message": "创建成功",
  "data": {
    "id": 101,
    "title": "Python工程师",
    "department": "计算机",
    "description": "负责后端开发",
    "status": "active",
    "salary": "15k"
  }
}

5) 【面试口播版答案】：面试官您好，针对校园招聘信息发布系统的API设计，我会从HTTP方法语义、请求参数分类、响应结构及错误码三方面说明，并解释设计原因。首先，HTTP方法区分操作：GET用于查询（幂等、可缓存），POST用于创建（非幂等），PUT用于更新（幂等），DELETE用于删除（幂等）。请求参数分为三类：路径参数（如职位ID，标识唯一资源，用GET/PUT/DELETE，需验证唯一性），查询参数（如部门、页码，用于筛选，用GET，无唯一性），请求体（如职位详情，用于创建/更新，用POST/PUT，需验证完整性）。响应结构包含HTTP状态码（200成功，4xx/5xx错误），成功返回data（业务数据），错误返回code（错误码）、message（描述）、data（错误详情）。错误码遵循HTTP标准（4xx客户端，5xx服务器），自定义细粒度（如4001参数缺失），确保标准化。选择这些设计是因为符合RESTful最佳实践，提升接口可读性、可维护性，降低客户端错误处理成本，同时通过URL版本管理（如/api/v1/）支持系统迭代。总结来说，通过分类参数、标准化响应和错误码，能构建清晰、易用的API接口，满足校园招聘系统的需求。

6) 【追问清单】：

问题1：API版本如何管理？
回答要点：采用URL版本号（如/api/v1/），避免版本冲突，便于后续迭代。
问题2：错误码是否与HTTP标准状态码冲突？
回答要点：遵循HTTP状态码（4xx客户端，5xx服务器），自定义错误码（如4001）补充细粒度，不冲突。
问题3：参数类型选择依据是什么？
回答要点：路径参数用于唯一标识（如ID），查询参数用于可选筛选（如分页），请求体用于核心数据（如创建数据），根据资源操作类型选择。
问题4：如何处理参数验证？
回答要点：对路径参数验证唯一性（如职位ID存在），查询参数验证范围（如页码>=1），请求体验证数据完整性（如必填字段）。
问题5：跨平台兼容性如何考虑？
回答要点：采用JSON格式，符合主流语言（如Java、Python、JavaScript）的序列化/反序列化，确保跨平台兼容。

7) 【常见坑/雷区】：

坑1：错误码与HTTP状态码混淆，如用200表示错误。
避免方法：明确状态码表示请求是否被接收/处理，错误码表示具体错误类型。
坑2：参数类型选择不当，如用查询参数传敏感数据（如密码）。
避免方法：敏感数据用请求体（POST/PUT），查询参数仅用于非敏感筛选。
坑3：忽略参数验证，如路径参数未验证唯一性。
避免方法：对路径参数进行唯一性验证（如职位ID存在），确保资源唯一。
坑4：缓存策略不当，如GET请求的查询参数未考虑缓存。
避免方法：根据查询参数是否变化决定缓存策略（如分页参数变化则不缓存）。
坑5：版本冲突，如旧版本API路径与新版冲突。
避免方法：采用URL版本号，如/api/v1/，避免路径冲突。