前后端开发规范

后端开发规范

1. 接口文档管理
   新开发的后端接口必须在 Apifox 中进行详细记录。具体要求如下：

   • 每个接口需明确描述其功能、请求方式（如 GET、POST 等）、请求参数及参数类型。
   • 在接口的“成功示例”中，提供完整的返回结果集，并对每个字段进行清晰注释，说明字段含义、数据类型及可能的取值范围。
     示例：

     {
       "code": 200,                  // 状态码，200 表示成功
       "message": "操作成功",         // 提示信息
       "data": {                     // 返回数据
         "userId": 123,              // 用户ID，整数类型
         "username": "testUser",     // 用户名，字符串类型
         "createdAt": "2025-04-08"   // 创建时间，格式为 YYYY-MM-DD
       }
     }
     

   • 确保接口文档与实际代码保持一致，避免因文档不准确导致前后端联调问题。

2. 前后端职责划分

   • 前端职责：前端仅负责数据展示和用户交互，所有涉及业务逻辑的计算均交由后端处理。
     • 前端应避免直接对数据进行复杂计算或逻辑判断，例如金额计算、日期格式化等，这些操作统一由后端完成并返回结果。
   • 后端职责：后端需承担所有业务逻辑处理及数据校验工作，包括但不限于：
     • 表单提交的数据校验（如字段是否为空、数据格式是否正确、值范围是否合法等）。
     • 数据计算、逻辑判断及异常处理。
     • 返回标准化的错误信息，便于前端进行错误提示。

3. 表单校验

   • 原则上，表单提交的校验工作由后端全权负责，前端无需重复校验。
   • 若前端需要实现简单的校验（如必填项检查）（正常情况下无需做任何校验），仅为提升用户体验，不能替代后端校验。
   • 后端在校验失败时，需返回清晰的错误信息，告知具体的校验失败原因，例如：

     {
       "code": 400,
       "message": "参数错误",
       "errors": [
         {
           "field": "username",
           "message": "用户名不能为空"
         },
         {
           "field": "email",
           "message": "邮箱格式不正确"
         }
       ]
     }
     

4. 接口文档目录结构规范

   • 接口文档的目录结构需按照实际应用（App）的功能模块或入口目录进行组织，确保文档结构清晰、易于查找。

   • 具体要求如下：

     • 按照项目的功能模块划分目录，例如：用户管理、订单管理、支付管理 等。
     • 如果项目有明确的入口层级（如 /api/v1、/api/v2），则在 Apifox 中创建对应的目录层级，与实际接口路径保持一致。
       示例目录结构：

       ├── 用户管理
       │   ├── 登录接口 (POST /api/v1/user/login)
       │   ├── 注册接口 (POST /api/v1/user/register)
       │   └── 用户信息查询 (GET /api/v1/user/info)
       ├── 订单管理
       │   ├── 创建订单 (POST /api/v1/order/create)
       │   ├── 查询订单详情 (GET /api/v1/order/detail)
       │   └── 取消订单 (POST /api/v1/order/cancel)
       ├── 支付管理
       │   ├── 发起支付 (POST /api/v1/pay/initiate)
       │   └── 支付结果查询 (GET /api/v1/pay/status)
       

     • 如果某个模块下有子模块，则进一步细分目录。例如，在 订单管理 下可以增加 退款管理 子目录：

       ├── 订单管理
       │   ├── 退款管理
       │   │   ├── 申请退款 (POST /api/v1/order/refund/apply)
       │   │   └── 查询退款状态 (GET /api/v1/order/refund/status)
       

   • 命名规范：

     • 目录名称和接口名称应简洁明了，避免使用模糊词汇。
     • 使用小写字母和中划线（-）分隔单词，例如：用户管理 -> user-management。
     • 接口路径需与后端实际路由保持一致，便于前后端对接。

   • 维护要求：

     • 新增接口时，需严格按照目录结构添加到对应模块下，避免随意放置导致文档混乱。
     • 定期检查接口文档目录，清理废弃接口或调整目录结构以适应项目需求变化。