zhangshun/docs/api-v0.1.md

mydreamjob API v0.1 接口清单

版本: 0.1.0 | 更新日期: 2026-08-03 | 基础路径: http://localhost:8080/api/v1

认证模块 /api/v1/auth

1. 发送短信验证码（Mock）

POST /api/v1/auth/sms/send
Query: phone=13800000001, purpose=login

响应示例:

{
  "code": 200,
  "message": "success",
  "data": { "message": "验证码已发送（Mock）" },
  "requestId": "a1b2c3d4e5f6g7h8",
  "timestamp": "2026-08-03T10:00:00Z"
}

限制:

• 60秒内同一手机号只能发送1次
• 5次错误后锁定5分钟
• Mock 环境验证码不输出到日志；本地按 docs/frontend-integration.md §3 的受控方式取得（生产禁止查表）

2. Mock 登录

POST /api/v1/auth/login
Content-Type: application/json

请求体:

{
  "phone": "13800000001",
  "code": "123456",
  "purpose": "login"
}

响应示例:

{
  "code": 201,
  "message": "created",
  "data": {
    "userId": 1,
    "phone": "13800000001",
    "nickname": "管理员",
    "role": "ADMIN",
    "accessToken": "eyJhbGc...",
    "refreshToken": "eyJhbGc...",
    "expiresIn": 86400
  },
  "requestId": "a1b2c3d4e5f6g7h8",
  "timestamp": "2026-08-03T10:00:00Z"
}

3. 当前用户信息

GET /api/v1/auth/me
Authorization: Bearer <accessToken>

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "phone": "13800000001",
    "email": "admin@mydreamjob.com",
    "nickname": "管理员",
    "role": "ADMIN",
    "active": true,
    "verified": true,
    "createdAt": "2026-08-03T10:00:00Z"
  },
  "requestId": "a1b2c3d4e5f6g7h8",
  "timestamp": "2026-08-03T10:00:00Z"
}

系统模块 /api/v1

4. 健康检查

GET /api/v1/health

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "status": "UP",
    "components": {
      "db": { "status": "UP", "detail": { "database": "MySQL" } },
      "redis": { "status": "UP" },
      "diskSpace": { "status": "UP" },
      "rabbitmq": { "status": "UP" }
    }
  },
  "requestId": "a1b2c3d4e5f6g7h8",
  "timestamp": "2026-08-03T10:00:00Z"
}

5. 应用信息

GET /api/v1/info

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "application": "mydreamjob-server",
    "version": "0.0.1-SNAPSHOT",
    "javaVersion": "17.0.18",
    "uptimeSeconds": 120,
    "springProfile": "dev"
  },
  "requestId": "a1b2c3d4e5f6g7h8",
  "timestamp": "2026-08-03T10:00:00Z"
}

6. 详细健康检查

GET /api/v1/health/details

返回 Actuator 健康端点的完整信息，包括各依赖服务状态。

错误码说明

错误码	含义	场景
1000	success	成功
1001	bad request	请求参数错误
1002	internal server error	服务器内部错误
2001	unauthorized	未认证
2002	forbidden	无权限
2003	token expired	Token 已过期
2004	token invalid	Token 无效
2005	invalid credentials	凭证错误
3001	sms code sent	验证码已发送
3002	sms code expired	验证码已过期
3003	sms code invalid	验证码错误
3004	sms code attempts exceeded	验证码尝试次数超限
3005	sms rate limited	短信发送频率限制
4001	user not found	用户不存在
4002	user already exists	用户已存在
9002	rate limited	系统限流

Swagger/OpenAPI 文档

http://localhost:8080/swagger-ui.html
http://localhost:8080/v3/api-docs

4. 刷新 Token（S02）

POST /api/v1/auth/refresh
Content-Type: application/json

{ "refreshToken": "<refreshToken>" }

• 匿名可调用；是否成功取决于 Refresh Token 校验结果。
• 只接受 Refresh Token；把 Access Token 传进来一律 401。
• 请求体只允许 refreshToken 一个字段；Token 不接受 query/path 参数。
• 成功后返回新的 Token 对，旧 Refresh Token 立即失效（强制轮换）。
• 已消费/已撤销的 Refresh Token 再次提交 → 401，并撤销该登录会话（重放处置）。
• 失败响应不说明 Token 是"不存在""已消费"还是"已撤销"。

成功响应:

{
  "code": 200,
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "expiresIn": 86400
  },
  "requestId": "<request-id>"
}

5. 登出（S02）

POST /api/v1/auth/logout
Authorization: Bearer <accessToken>

• 必须已认证；无请求体。
• 身份与会话来自 Access Token，不接受客户端传入 userId/sessionId/refreshToken。
• 只撤销当前登录会话，其他设备会话不受影响。
• 重复登出按幂等处理；成功响应不包含任何 Token。

Token 与会话模型（S02）

Token	用途	说明
Access Token	普通业务接口的 Authorization 头	带 type=access，有效期 24h；每次请求都会校验服务端会话状态
Refresh Token	仅用于 POST /auth/refresh	带 type=refresh，有效期 7 天；不落库，数据库只保存其 HMAC-SHA256 摘要

• Access 与 Refresh 使用不同签名密钥，交叉验签必然失败。
• 每次登录创建独立的登录会话（sessionId）；同一用户可同时存在多个会话。
• 登出只撤销当前会话；账号注销完成、用户禁用会撤销该用户全部会话。
• 本版不再兼容无 type 的旧 Token（所有旧 Token 失效，用户需重新登录一次）。
• Token 原文不进入数据库、日志、审计、URL 或错误响应。

已知限制

1. 短信验证码为 Mock 实现，应用日志不输出验证码，不发送真实短信；未接入真实供应商时发码返回“服务不可用”
2. 无企业注册/认证流程
3. 无密码修改/重置功能
4. 未提供查看全部登录设备、远程踢出单个设备、Token introspection 等接口
5. RabbitMQ 未实现消息监听器（仅队列定义）
6. Actuator 健康检查部分依赖（Redis/RabbitMQ）在未启动时返回 DOWN