数据紧校验规范

规范描述

本规范旨在为后端 API 的数据校验与错误处理提供统一的标准，确保前后端在交互过程中能够高效、准确地传递和处理错误信息。规范内容包括以下几个方面：

1. 统一响应结构

所有后端 API 接口的响应均采用统一的 JSON 格式，主要包含以下字段：

data：用于存放响应的具体数据内容。
- 在请求成功时，data 包含所需的返回数据。
- 在请求失败时，data 包含错误详情，如字段校验错误信息。
code：状态码，用于标识请求的处理结果。
- 0 表示请求未通过。
- 其他值根据具体业务需求定义。
ok：布尔值，指示请求是否成功。
- true 表示成功。
- false 表示失败。
msg：用于传递业务逻辑失败的提示信息。
- 当仅存在字段校验失败时，msg 为 null。
- 当业务逻辑失败时，msg 包含具体的错误提示信息。

2. 字段校验规则

必填字段：每个 API 接口需明确请求参数的必填字段、数据类型和格式要求。
校验逻辑：
- 字段缺失：当请求参数中缺少必填字段时，视为校验失败。
- 数据类型不符：当请求参数的数据类型不符合预期时，视为校验失败。
- 格式错误：如邮箱格式不正确、密码强度不足等，视为校验失败。
错误信息：
- 每个校验失败的字段应返回具体的错误提示信息，便于前端定位和展示错误。
- 错误提示信息应清晰、简洁，易于理解。

3. 错误分类与处理

字段校验错误：
- 当请求参数中存在一个或多个字段校验失败时，后端返回包含 data 字段的响应。
- data 是一个数组，每个元素包含 field（失败的字段名称）和 messages（对应的错误提示信息）。
业务逻辑错误：
- 当请求参数校验通过，但因业务逻辑问题导致请求失败时，后端返回包含 msg 字段的响应。
- 此时，data 通常为 null 或包含具体的数据。
其他错误：
- 如系统错误、未预期的异常等，后端应返回适当的错误响应。
- 错误响应的具体格式可根据实际情况调整，但应尽量保持与统一响应结构的一致性。

4. 前端处理流程

前端在接收到 API 响应后，应按照以下步骤进行处理：

检查 ok 字段：
- 若 ok 为 true，则处理成功逻辑。
- 若 ok 为 false，则进一步检查错误信息。
处理业务逻辑错误：
- 检查 msg 字段。
- 若 msg 不为空，弹出提示框显示 msg 内容。
处理字段校验错误：
- 检查 data 字段。
- 若 data 不为空，解析 data 数组，逐个处理校验错误信息。
- 根据具体前端框架，将错误提示显示在对应的输入元素旁边。

5. 状态码说明

code 字段：
- 当前规范中，code 字段主要用于表示请求是否通过。
- 0 表示请求未通过。
- 其他状态码将在后续接口中根据具体业务需求进行定义和使用。
- 前端开发人员在当前阶段无需关注 code 字段，除非在特殊情况下需要处理特定的状态码。

请求和响应示例

请求接口

请求格式

接口 /api/v1/user/login 接收以下格式的数据：

{
  "email": "用户邮箱",
  "password": "用户密码",
  "user_type": "用户类型"
}

字段说明

email: 用户的邮箱地址，字符串类型，必填。
password: 用户的密码，字符串类型，必填。
user_type: 用户类型，字符串类型，必填。

后端响应格式

后端返回标准的 JSON 格式响应，根据不同情况分为以下三种：

1. 多字段校验失败

当请求体为空或存在多个字段校验失败时，响应如下：

请求示例：

{}

响应示例：

{
  "data": [
    {
      "field": "email",
      "messages": ["email can not be empty"]
    },
    {
      "field": "password",
      "messages": ["password can not be empty"]
    },
    {
      "field": "user_type",
      "messages": ["user_type can not be empty"]
    }
  ],
  "code": 0,
  "ok": false,
  "msg": null
}

字段说明

data: 包含所有校验失败的字段及对应的提示信息。
- field: 失败的字段名称。
- messages: 对应字段的校验错误提示，数组形式，一个字段可包含多个提示。
code: 状态码，表示请求处理状态（如 0 表示请求未通过）。
ok: 请求处理结果，false 表示校验未通过。
msg: 业务逻辑失败的提示信息，若仅为校验失败则为 null。

2. 单个字段校验失败

当仅有一个字段校验失败时，响应如下：

请求示例：

{
  "email": "litong@hawaii.com",
  "password": "Xxxxx@2025"
}

响应示例：

{
  "data": [
    {
      "field": "user_type",
      "messages": ["user_type can not be empty"]
    }
  ],
  "code": 0,
  "ok": false,
  "msg": null
}

此时前端仅需补充 user_type 字段，即可通过校验。

3. 校验通过但业务逻辑失败

当所有字段校验通过，但业务逻辑（如用户名或密码错误）失败时，响应如下：

响应示例：

{
  "data": null,
  "ok": false,
  "msg": "username or password is not correct",
  "code": 0
}

字段说明

msg: 详细的业务错误提示，例如 “用户名或密码不正确”。
data: 若非校验错误，通常为 null。

结论与前端处理指南

字段校验: 若请求体中字段缺失或不符合规则，后端返回包含 data 字段的响应，详细列出所有校验失败的字段及提示信息。
业务逻辑错误: 当校验通过但业务逻辑失败时，后端返回带有 msg 的提示，且 data 为 null 或具体的数据。
前端处理:
- 根据 ok 字段判断请求是否成功。
- 若 ok 为 false：
  - 判断 msg 是否为空：
    - 若不为空，弹出提示框显示 msg 内容。
  - 判断 data 是否为空：
    - 若不为空，解析 data 并根据相应逻辑显示校验错误提示（例如，将 email 字段的错误信息显示在对应的输入框旁）。
- 示例代码（JavaScript）：

if (response.ok) {
  // 处理成功逻辑
} else {
  if (response.msg) {
    // 弹出提示框显示 msg 内容
    alert(response.msg);
  }

  if (response.data) {
    // 解析 data 并显示校验错误提示
    response.data.forEach((error) => {
      const field = error.field;
      const messages = error.messages;
      // 根据具体前端框架，将 messages 显示在对应的 input 元素旁
      displayFieldErrors(field, messages);
    });
  }
}

code 字段: 当前无需关注，只有在特殊情况下使用，具体使用场景将在后续接口中说明。
JavaScript 的真假判断: 以下情况会被视为 false：
- null
- undefined
- false
- 0
- NaN
- 空字符串 ''