个人使用的接口文档
本文档为[系统名称]接口的标准沟通文档，旨在XXX。 功能描述：用户通过输入账号、密码及验证码完成身份校验，校验通过后获取访问令牌（Token）和刷新令牌，访问令牌用于后续接口调用的身份认证。 请求示例： 成功响应示例： 错误响应示例： 本文档中状态码分为业务状态码（接口响应中的code字段）和HTTP状态码，本章节主要说明业务状态码的含义及对应解决方案。1. 文档概述
1.1 文档目的
1.2 文档修订记录
修订版本 修订时间 修订人 修订内容 V1.0 2024-01-01 [姓名] 初始版本，完成用户管理模块核心接口编写 1.3 接口通用规则
1.3.1 基础URL
环境类型 基础URL前缀 使用说明 开发环境 http://dev-[系统域名]/api/v1 供开发人员日常开发、调试使用 测试环境 http://test-[系统域名]/api/v1 供测试人员执行功能测试、集成测试使用 预发布环境 https://uat-[系统域名]/api/v1 模拟生产环境配置，用于上线前用户最终验证 生产环境 https://[系统域名]/api/v1 正式对外提供服务的环境，需严格控制访问权限 1.3.2 数据与编码规范
2. 接口详细说明
2.1 接口列表总览
接口名称 接口路径 请求方法 核心功能 用户认证 /auth/login POST 用户通过账号密码获取访问令牌（Token） 2.2 用户认证接口（/auth/login）
2.2.1 接口基础信息
2.2.2 请求头参数
字段名 字段值 是否必填 说明 Content-Type application/json 是 指定请求数据格式为JSON 2.2.3 请求参数（Body）
字段名 类型 是否必填 描述 格式要求 username string 是 用户账号 长度为4-20位，支持字母、数字及下划线 password string 是 用户密码 长度为8-20位，需包含大小写字母、数字及特殊字符 captcha string 是 验证码 长度为4位，区分大小写，需与前端展示的验证码一致
{
"username": "admin",
"password": "Admin@123456",
"captcha": "8FzQ"
}2.2.4 响应参数
2.2.4.1 成功响应
字段名 类型 描述 补充说明 code integer 业务成功码 固定为200，表示业务处理成功 message string 响应信息描述 成功时默认返回"登录成功" data object 响应数据主体 包含认证相关的令牌信息 data.token string 访问令牌 有效时长为2小时，后续接口调用需携带此令牌 data.refreshToken string 刷新令牌 有效时长为7天，用于访问令牌过期后刷新获取新令牌 2.2.4.2 错误响应
字段名 类型 描述 补充说明 code integer 业务错误码 不同错误场景对应不同的错误码，具体参考第3章节状态码说明 message string 错误信息 明确提示错误原因，便于问题排查 data object 错误响应体 错误场景下通常为null {
"code": 200,
"message": "登录成功",
"data": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
"refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"
}
}{
"code": 4001,
"message": "账号或密码错误",
"data": null
}3. 状态码说明
状态码 错误类型 错误描述 解决方案 200 成功 业务处理成功 无需处理，正常后续流程即可 400 参数错误 请求参数缺失、格式错误或不符合校验规则（具体见错误信息） 根据错误信息提示，按接口请求参数要求修正参数格式、补充缺失参数 401 认证错误 未携带认证令牌、令牌已过期或令牌无效 重新调用登录接口获取有效令牌，在请求头中添加Authorization字段（格式：Bearer [Token]） 403 权限错误 当前用户无该接口的访问权限 联系系统管理员申请对应接口的访问权限，权限开通后再进行调用 404 资源错误 接口路径不存在或请求的资源不存在 核查接口路径是否与文档一致，确认请求的资源标识（如用户ID）是否有效 500 系统错误 服务器内部错误，无法正常处理请求 记录完整的错误响应信息（含请求参数、时间戳），联系后端开发人员排查问题 4. 附录
4.1 数据类型说明
类型 说明 string 字符串类型 integer 整数类型 long 长整数类型 boolean 布尔类型识 object 对象类型 array 数组类型