coder-common-thin-backend/api/authentication/登录认证API.md

登录认证API

概述

登录认证模块提供用户登录、退出、注册等功能，使用Sa-Token进行身份认证和会话管理。

接口列表

1. 用户登录

接口地址: POST /auth/login

接口描述: 用户使用账号密码登录系统

是否需要认证: 否

请求参数:

{
  "loginName": "admin",
  "password": "123456",
  "codeKey": "uuid-key",
  "securityCode": "1234",
  "rememberMe": false
}

请求参数说明:

参数名	类型	必填	说明	校验规则
loginName	String	是	登录账号	长度3-16位，只能包含字母和数字
password	String	是	登录密码	不能为空
codeKey	String	是	验证码UUID	不能为空
securityCode	String	是	验证码	不能为空
rememberMe	Boolean	否	记住登录	默认false

响应示例:

{
  "status": 200,
  "msg": "SUCCESS",
  "data": {
    "tokenName": "Authorization",
    "tokenValue": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
  },
  "traceId": "trace-123456"
}

响应参数说明:

参数名	类型	说明
tokenName	String	Token名称
tokenValue	String	Token值

错误码:

状态码	错误信息	说明
400	账号长度为 3-16 位	登录账号长度不符合要求
400	账号格式为数字以及字母	登录账号格式不正确
400	请输入登录名	登录名为空
400	请输入密码	密码为空
400	验证码已失效	验证码Key无效
400	请输入验证码	验证码为空
400	验证码错误	验证码不正确
400	用户不存在	用户账号不存在
400	密码错误	密码不正确
400	账号已被停用	用户账号被禁用
400	账号已被锁定	用户账号被锁定

调用示例:

curl -X POST \
  http://localhost:18099/auth/login \
  -H 'Content-Type: application/json' \
  -d '{
    "loginName": "admin",
    "password": "123456",
    "codeKey": "550e8400-e29b-41d4-a716-446655440000",
    "securityCode": "1234",
    "rememberMe": false
  }'

---

2. 用户退出

接口地址: GET /auth/logout

接口描述: 用户退出登录，清除会话信息

是否需要认证: 是

请求头:

Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

请求参数: 无

响应示例:

{
  "status": 200,
  "msg": "SUCCESS",
  "data": "退出成功",
  "traceId": "trace-123456"
}

错误码:

状态码	错误信息	说明
401	当前会话未登录	用户未登录或Token无效

调用示例:

curl -X GET \
  http://localhost:18099/auth/logout \
  -H 'Authorization: your-token-value'

---

3. 用户注册

接口地址: POST /auth/register

接口描述: 新用户注册账号

是否需要认证: 否

请求参数:

{
  "loginName": "newuser",
  "password": "123456",
  "userName": "新用户",
  "codeKey": "uuid-key",
  "securityCode": "1234"
}

请求参数说明:

参数名	类型	必填	说明	校验规则
loginName	String	是	登录账号	长度3-16位，只能包含字母和数字
password	String	是	登录密码	不能为空
userName	String	是	用户姓名	不能为空
codeKey	String	是	验证码UUID	不能为空
securityCode	String	是	验证码	不能为空

响应示例:

{
  "status": 200,
  "msg": "SUCCESS",
  "data": "注册成功",
  "traceId": "trace-123456"
}

错误码:

状态码	错误信息	说明
400	账号长度为 3-16 位	登录账号长度不符合要求
400	账号格式为数字以及字母	登录账号格式不正确
400	请输入登录名	登录名为空
400	请输入密码	密码为空
400	请输入用户姓名	用户姓名为空
400	验证码已失效	验证码Key无效
400	请输入验证码	验证码为空
400	验证码错误	验证码不正确
400	账号已存在	登录账号已被注册

调用示例:

curl -X POST \
  http://localhost:18099/auth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "loginName": "newuser",
    "password": "123456",
    "userName": "新用户",
    "codeKey": "550e8400-e29b-41d4-a716-446655440000",
    "securityCode": "1234"
  }'

---

认证流程说明

1. 登录流程

1. 用户获取验证码（调用验证码接口）
2. 用户输入账号、密码、验证码
3. 系统验证验证码有效性
4. 系统验证用户账号和密码
5. 系统检查用户状态（是否禁用/锁定）
6. 生成Token并返回给用户
7. 用户后续请求携带Token

2. Token使用

• Token需要在请求头中携带：Authorization: token-value
• Token有过期时间，过期后需要重新登录
• 系统支持多设备登录
• 管理员可以强制用户下线

3. 权限验证

• 登录后系统会根据用户角色加载权限
• 每个接口都会验证用户是否有相应权限
• 超级管理员拥有所有权限

4. 会话管理

• 用户登录信息存储在Redis中
• 支持会话延长
• 支持记住登录功能
• 系统会记录用户登录日志

安全特性

1. 密码加密: 使用盐值加密存储密码
2. 验证码保护: 防止暴力破解
3. 账号锁定: 连续错误3次自动锁定
4. IP限制: 可配置IP白名单/黑名单
5. 会话安全: Token有效期管理
6. 日志记录: 记录所有登录操作

注意事项

1. 验证码有效期为5分钟
2. Token默认有效期为30天
3. 账号锁定时间为10分钟
4. 注册功能可通过配置开启/关闭
5. 建议在生产环境中启用HTTPS