wanglei/EchoChat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feature/phase2e-2-meeting-mvp
EchoChat/docs/api/frontend/auth.md
bujinyuan c3e8600b24 fix: 前后台 Token Redis 存储隔离，修复同账号互相覆盖问题 
核心变更：
- Redis key 加入 clientType 前缀：echo:auth:token:{frontend|admin}:{user_id}
- JWT Claims 新增 client_type 字段区分前台/管理端
- 新增 constants/client_type.go 定义 ClientTypeFrontend / ClientTypeAdmin
- 全链路传递 clientType：Controller → Service → TokenStore → Redis
- 中间件从 JWT Claims 提取 clientType 做 Redis 校验
- 登出只删除当前端 Token，不影响另一端

前端变更：
- 管理端 login API 改为调用 POST /api/v1/admin/auth/login（之前错误调用了前台接口）

文档更新：
- 系统设计文档、实施计划、API文档、开发规范、项目进度全部同步

Made-with: Cursor
2026-03-02 14:28:45 +08:00

6.6 KiB
Raw Permalink 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": "张三"
}

成功响应（200 OK）：

{
    "code": 0,
    "message": "success",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
        "expires_in": 7200,
        "user": {
            "id": 1,
            "username": "zhangsan",
            "email": "zhangsan@example.com",
            "nickname": "张三",
            "avatar": "",
            "gender": 0,
            "roles": ["user"]
        }
    },
    "trace_id": "6478824e-2926-4d35-aa5f-047c8cfbb36b",
    "time": "2026-02-28 16:42:03"
}

expires_in 为 Access Token 有效期（秒），当前配置为 7200 秒（2 小时）。Refresh Token 有效期为 7 天。

可能的错误：

HTTP 状态码 说明
400 参数校验失败 / 用户名或邮箱已被注册

2. 用户登录

POST /api/v1/auth/login

权限： 公开

请求参数：

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

请求示例：

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

成功响应（200 OK）：

{
    "code": 0,
    "message": "success",
    "data": {
        "token": "eyJhbGciOiJIUzI1NiIs...",
        "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
        "expires_in": 7200,
        "user": {
            "id": 1,
            "username": "zhangsan",
            "email": "zhangsan@example.com",
            "nickname": "张三",
            "avatar": "",
            "gender": 0,
            "roles": ["user"]
        }
    },
    "trace_id": "fe290a90-00af-4c6b-8af7-ba6ae1d57d20",
    "time": "2026-02-28 16:42:04"
}

可能的错误：

HTTP 状态码 说明
400 参数校验失败
401 账号或密码错误
403 账号已被禁用 / 账号已注销
404 用户不存在

3. 退出登录

POST /api/v1/auth/logout

权限： 需认证

说明： 采用有状态 JWT 方案，Token 按 clientType 隔离存储在 Redis 中（echo:auth:token:frontend:{user_id} 和 echo:auth:refresh:frontend:{user_id}）。登出时服务端只删除前台端的 Token，不影响管理端。客户端也应同步清除本地存储的 Token。

成功响应：

{
    "code": 0,
    "message": "success",
    "data": null,
    "trace_id": "...",
    "time": "2026-02-28 16:42:05"
}

4. 刷新 Token

POST /api/v1/auth/refresh-token

权限： 公开（携带 refresh_token）

请求参数：

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

请求示例：

{
    "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

成功响应：

{
    "code": 0,
    "message": "success",
    "data": {
        "token": "eyJhbG...(新 Access Token)",
        "refresh_token": "eyJhbG...(新 Refresh Token)",
        "expires_in": 7200,
        "user": {
            "id": 1,
            "username": "zhangsan",
            "email": "zhangsan@example.com",
            "nickname": "张三",
            "avatar": "",
            "gender": 0,
            "roles": ["user"]
        }
    },
    "trace_id": "...",
    "time": "2026-02-28 16:42:06"
}

可能的错误：

HTTP 状态码 说明
400 参数校验失败 / 无效的 Refresh Token 类型
401 Token 已过期或无效
403 账号已被禁用 / 账号已注销
404 用户不存在

5. 获取个人信息

GET /api/v1/auth/profile

权限： 需认证

成功响应：

{
    "code": 0,
    "message": "success",
    "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-27 10:00:00"
    },
    "trace_id": "...",
    "time": "2026-02-28 16:42:07"
}

profile 接口返回的 UserInfo 包含 phone 和 created_at 字段（相比登录响应中的用户信息更完整）。

6. 更新个人信息

PUT /api/v1/auth/profile

权限： 需认证

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

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

成功响应： 返回更新后的完整用户信息（与获取个人信息接口格式一致）。

7. 修改密码

PUT /api/v1/auth/password

权限： 需认证

请求参数：

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

成功响应：

{
    "code": 0,
    "message": "success",
    "data": null,
    "trace_id": "...",
    "time": "2026-02-28 16:42:08"
}

可能的错误：

HTTP 状态码 说明
400 参数校验失败
401 原密码错误
404 用户不存在