hzdyjs/docs/开发文档/API/API文档基础规范.md

API 文档基础规范

📋 文档说明

本文档记录项目 API 接口的通用规范和标准，包括请求方式、参数说明、响应格式等。所有 API 接口必须遵循此基础规范。

🔧 基础信息

• 基础路径: /api
• 响应格式: JSON
• 字符编码: UTF-8
• 权限认证: Sa-Token + JWT
• 版本: v1.0

---

🔐 请求头规范（强制性）

所有需要认证的接口必须在请求头中包含 Token，格式如下：

{
    "Content-Type": "application/json;charset=utf-8",
    "Authorization": "Bearer {access_token}",
    "clientid": "e5cd7e4891bf95d1d19206ce24a7b32e",
    "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8",
    "referer": "http://localhost/login?redirect=%252Findex"
}

📋 请求头字段说明

字段名	必填	说明	示例值
Authorization	是	Bearer + Token 值（⚠️ 注意空格）	"Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
clientid	是	客户端 ID，用于权限验证	"e5cd7e4891bf95d1d19206ce24a7b32e"
Content-Type	是	请求内容类型	"application/json;charset=utf-8"
Accept-Language	是	语言设置，用于国际化	"zh-CN,zh;q=0.9,en;q=0.8"
referer	是	来源页面，用于安全验证	"http://localhost/login?redirect=%252Findex"

⚠️ Token 格式强制要求

• ✅ 正确: "Authorization": "Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
• ❌ 错误: "Authorization": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." （缺少 Bearer 前缀）
• ❌ 错误: "Authorization": "Bearer eyJ0eXAi..." （Bearer 后面没有空格）

---

🔴 统一响应格式（强制性）

⚠️ 所有 API 接口必须严格遵循以下统一响应格式！

📊 分页列表响应格式

{
    "total": 100,
    "rows": [
        {
            "id": 1,
            "name": "示例数据1",
            "createTime": "2025-06-30 12:00:00"
        },
        {
            "id": 2,
            "name": "示例数据2",
            "createTime": "2025-06-30 12:01:00"
        }
    ],
    "code": 200,
    "msg": "查询成功"
}

🎯 非分页列表响应格式

{
    "code": 200,
    "msg": "查询成功",
    "data": [
        {
            "id": 1,
            "name": "示例数据1"
        },
        {
            "id": 2,
            "name": "示例数据2"
        }
    ]
}

🎯 单条数据响应格式

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "id": 1,
        "name": "示例数据",
        "createTime": "2025-06-30 12:00:00"
    }
}

🎯 操作成功响应格式（无数据）

{
    "code": 200,
    "msg": "操作成功",
    "data": null
}

❌ 错误响应格式

{
    "code": 400,
    "msg": "参数错误：用户名不能为空",
    "data": null
}

---

📋 状态码规范

✅ 成功状态码

• 200 - 操作成功
• 201 - 创建成功

🚫 客户端错误（4xx）

• 400 - 请求参数错误
• 401 - 未认证/认证失败
• 403 - 无权限访问
• 404 - 资源不存在
• 409 - 数据冲突

💥 服务端错误（5xx）

• 500 - 服务器内部错误
• 502 - 网关错误
• 503 - 服务不可用

---

🚨 开发强制要求

1. 请求头必须包含 Bearer Token 格式的 Authorization
2. 分页接口必须直接返回 TableDataInfo 格式（total、rows、code、msg）
3. 非分页接口必须使用 R 类型包装返回结果
4. 单条数据接口必须使用 R 类型包装返回结果
5. 操作类接口必须使用 R 类型包装返回结果
6. 必须包含 clientid、Content-Type 等必要请求头

---

📝 业务错误码

通用错误码

错误码	说明	解决方案
40001	参数校验失败	检查请求参数格式和必填字段
40002	数据不存在	检查资源 ID 是否正确
40003	权限不足	联系管理员分配权限
40004	操作失败	重试或联系技术支持
40005	数据冲突	检查数据是否重复

认证相关错误码

错误码	说明	解决方案
40101	Token 无效	重新登录获取 Token
40102	Token 已过期	刷新 Token 或重新登录
40103	用户未登录	请先登录
40104	客户端 ID 异常	检查 clientId 配置

业务模块错误码

错误码	说明	解决方案
41001	物业报修相关错误	参考物业报修 API 文档
41002	满意度调查相关错误	参考满意度调查 API 文档

---

📚 数据字典

🎯 通用状态

值	说明	备注
0	停用	不可用状态
1	正常	可用状态

🎯 是否标识

值	说明	备注
0	否	false
1	是	true

🎯 删除标识

值	说明	备注
0	正常	未删除
1	删除	已删除

🎯 用户类型

值	说明	角色映射
1	学生	student、学生、stu 等角色映射为此值
2	教师	teacher、老师、教师、教职工、tea 等角色映射为此值
3	超级管理员	admin、管理员、超级管理员、administrator 等角色映射为此值

---

⚙️ 开发配置说明

🔧 接口测试工具

推荐使用以下工具进行接口测试：

• Postman: 图形化接口测试工具
• Apifox: 国产 API 管理工具
• curl: 命令行工具

🔧 时间格式规范

所有时间字段统一使用以下格式：

• 数据库存储: YYYY-MM-DD HH:mm:ss
• API 传输: ISO 8601格式 YYYY-MM-DDTHH:mm:ss.sssZ

🔧 分页参数规范

所有分页接口统一使用以下参数：

• pageNum: 页码，从 1 开始
• pageSize: 页大小，默认 10

🔧 安全传输规范

1. 密码安全:

   • BCrypt 哈希加密存储
   • 登录失败次数限制
   • 账户自动锁定机制

2. 传输安全:

   • AES+RSA 混合加密
   • 防重放攻击保护
   • HTTPS 协议传输

3. 会话安全:

   • JWT Token 认证
   • Token 自动过期机制
   • 刷新 Token 机制

4. 多租户安全:

   • 租户隔离验证
   • 客户端权限控制
   • 不同设备类型支持

---

📞 联系方式

如有 API 相关问题，请联系开发团队或查看项目仓库的 Issues。

---

📝 维护: API 基础规范文档
🔄 更新: 2025-07-01
�� 文件: API 文档基础规范.md