wanglei/EchoChat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8bed227060b9443bce57650260d191593ecfa437
EchoChat/docs/api/auth.md
bujinyuan 4458f40025 docs: 完善项目文档体系 
- 数据库 SQL 所有字段添加 COMMENT 注释，枚举字段详细标注各值含义
- 新增 docs/architecture/ 系统架构文档（分层架构、数据流、演进路径）
- API 文档按模块拆分为 8 个独立文档（auth/contact/im/meeting/notify/admin/websocket）
- 补充 README.md 项目说明（技术栈、架构、快速开始、功能规划、文档导航）

Made-with: Cursor
2026-02-27 16:27:07 +08:00

4.1 KiB
Raw Blame History

认证模块 API (Auth)

通用规范（认证方式、响应格式、错误码）见 README.md

接口列表

方法 路径 权限 说明
POST /api/v1/auth/register 公开 用户注册
POST /api/v1/auth/login 公开 用户登录
POST /api/v1/auth/logout 需认证 退出登录
POST /api/v1/auth/refresh-token 公开 刷新 Token
GET /api/v1/auth/profile 需认证 获取个人信息
PUT /api/v1/auth/profile 需认证 更新个人信息
PUT /api/v1/auth/password 需认证 修改密码

1. 用户注册

POST /api/v1/auth/register

权限： 公开

请求参数：

字段 类型 必填 规则 说明
username string 是 3-50 字符，字母数字下划线 用户名
email string 是 合法邮箱格式 邮箱地址
password string 是 6-50 字符 登录密码
nickname string 否 最多 50 字符 昵称，默认与用户名相同

请求示例：

{
    "username": "zhangsan",
    "email": "zhangsan@example.com",
    "password": "123456",
    "nickname": "张三"
}

成功响应：

{
    "code": 0,
    "message": "ok",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
        "expires_in": 604800,
        "user": {
            "id": 1,
            "username": "zhangsan",
            "email": "zhangsan@example.com",
            "nickname": "张三",
            "avatar": "",
            "roles": ["user"]
        }
    }
}

可能的错误码： 1001, 2001, 2002

2. 用户登录

POST /api/v1/auth/login

权限： 公开

请求参数：

字段 类型 必填 说明
account string 是 用户名或邮箱（自动识别格式）
password string 是 登录密码

请求示例：

{
    "account": "zhangsan",
    "password": "123456"
}

成功响应： 与注册接口返回格式一致

可能的错误码： 1001, 2003, 2004

3. 退出登录

POST /api/v1/auth/logout

权限： 需认证

说明： 服务端清除 Redis 中的 Token 记录，客户端需同步清除本地存储的 Token。

成功响应：

{
    "code": 0,
    "message": "ok",
    "data": null
}

4. 刷新 Token

POST /api/v1/auth/refresh-token

权限： 公开（携带 refresh_token）

请求参数：

字段 类型 必填 说明
refresh_token string 是 刷新令牌

成功响应：

{
    "code": 0,
    "message": "ok",
    "data": {
        "token": "eyJhbG...(新 Access Token)",
        "refresh_token": "eyJhbG...(新 Refresh Token)",
        "expires_in": 604800
    }
}

可能的错误码： 1002

5. 获取个人信息

GET /api/v1/auth/profile

权限： 需认证

成功响应：

{
    "code": 0,
    "message": "ok",
    "data": {
        "id": 1,
        "username": "zhangsan",
        "email": "zhangsan@example.com",
        "nickname": "张三",
        "avatar": "https://cdn.echochat.com/avatar/1.jpg",
        "gender": 1,
        "phone": "13800138000",
        "roles": ["user"],
        "created_at": "2026-02-27T10:00:00Z"
    }
}

6. 更新个人信息

PUT /api/v1/auth/profile

权限： 需认证

请求参数（均为可选，只传需要修改的字段）：

字段 类型 必填 说明
nickname string 否 新昵称
avatar string 否 新头像 URL
gender int 否 性别：0=未知，1=男，2=女
phone string 否 手机号

7. 修改密码

PUT /api/v1/auth/password

权限： 需认证

请求参数：

字段 类型 必填 说明
old_password string 是 原密码
new_password string 是 新密码（6-50 字符）

可能的错误码： 1001, 2003（原密码错误）