You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
119 lines
8.2 KiB
119 lines
8.2 KiB
职来后端接口联调说明
|
|
前端开发使用 线上联调环境 2026年9月22日
|
|
结论：前端统一通过 HTTPS 域名访问后端，业务请求前缀为 https://job.youthome.com.cn/api/v1。除注册、登录、短信验证码、刷新 Token 等匿名接口外，其余接口需要在 Authorization 请求头携带 Access Token。
|
|
一 联调地址
|
|
|
|
[TABLE]
|
|
用途 | 地址 | 使用说明
|
|
业务接口基地址 | https://job.youthome.com.cn/api/v1 | 前端环境变量中的 API Base URL
|
|
健康检查 | https://job.youthome.com.cn/api/v1/health | 返回 code=200 且 data.status=UP 表示后端可用
|
|
OpenAPI JSON | https://job.youthome.com.cn/api/v1/v3/api-docs | Apifox 导入或更新接口定义使用
|
|
WebSocket | wss://job.youthome.com.cn/api/v1/ws | 仅在对应实时功能启用时使用；不要使用 ws://
|
|
|
|
|
|
重要：不要直接请求服务器 IP、Jenkins 地址或 8010 端口。前端、Apifox 和浏览器都统一使用 HTTPS 域名，避免跨域、证书和环境切换问题。
|
|
二 Apifox 配置方法
|
|
在 Apifox 项目中选择导入数据，导入方式选 URL，填写 OpenAPI JSON 地址。
|
|
环境前置 URL 设置为 https://job.youthome.com.cn/api/v1。接口路径本身只保留 /auth/me、/jobs 等相对路径。
|
|
创建环境变量 AuthToken，用登录响应中的 accessToken 赋值。
|
|
需要认证的接口统一设置请求头 Authorization: Bearer {{AuthToken}}。
|
|
接口有调整时重新从 OpenAPI URL 增量导入，不要手工复制旧接口覆盖新定义。
|
|
三 通用请求和响应规则
|
|
|
|
[TABLE]
|
|
项目 | 规则
|
|
请求格式 | 普通业务接口使用 application/json；上传简历等文件接口使用 multipart/form-data。
|
|
认证请求头 | Authorization: Bearer <accessToken>。Refresh Token 不能代替 Access Token 访问业务接口。
|
|
请求追踪 | 可传 X-Request-Id；后端会在响应头和响应体返回 requestId，报错联调时请一并提供。
|
|
时间格式 | 按 OpenAPI 定义发送 ISO 8601 日期或日期时间，不要自行转换为中文日期。
|
|
分页 | 以接口定义中的 page、size 为准；不要在前端假设页码起点。
|
|
响应外层 | 通常为 code、message、data、requestId、timestamp。业务数据读取 data。
|
|
|
|
|
|
Authorization: Bearer {{AuthToken}}Content-Type: application/jsonX-Request-Id: web-20260922-0001
|
|
{ "code": 200, "message": "ok", "data": { }, "requestId": "...", "timestamp": "..."}
|
|
四 登录与会话使用顺序
|
|
|
|
[TABLE]
|
|
步骤 | 接口 | 前端处理
|
|
1 | POST /auth/sms/send | 按 purpose 发送验证码；purpose 必须使用后端支持的固定值。
|
|
2A | POST /auth/password/login | 手机号和密码登录；成功后保存 accessToken、refreshToken。
|
|
2B | POST /auth/login | 短信验证码登录；现接口文档标为 Mock 登录，生产前端不要作为正式入口，除非产品和后端明确确认。
|
|
3 | GET /auth/me | 登录后拉取用户 id、角色和当前身份信息。
|
|
4 | POST /auth/refresh | Access Token 过期时，用 Refresh Token 换取新 Token。
|
|
5 | POST /auth/logout | 退出登录；成功后清除前端保存的所有 Token 和用户状态。
|
|
|
|
|
|
Token 保存与刷新建议
|
|
Access Token 用于业务请求；Refresh Token 只提交给 /auth/refresh 和会话相关接口。
|
|
遇到 401 时只允许一次串行刷新；刷新成功后重放原请求，刷新失败则清理会话并跳转登录页。
|
|
不要把 Token 打印到控制台、错误上报、URL 查询参数或页面 DOM。
|
|
不同浏览器标签页同时刷新时要加前端互斥，避免多个 Refresh Token 并发重放。
|
|
五 学生 企业 管理员的区别
|
|
|
|
[TABLE]
|
|
身份 | 账号产生方式 | 登录方式 | 主要接口前缀
|
|
STUDENT | 现有短信登录流程可自动创建学生账号 | 短信登录或已设置密码后的密码登录 | /profile/me、/applications、/offers、/interviews
|
|
COMPANY | POST /auth/company/register 专用注册 | 注册成功直接返回 Token；之后可密码登录 | /companies/me、/company、/jobs
|
|
ADMIN | 不提供公开注册，由管理员初始化或后台受控创建 | 使用现有认证方式登录 | /admin
|
|
|
|
|
|
前端路由判断：登录成功后以 /auth/me 返回的角色为准。不要让客户端提交 role 来决定身份，也不要仅依据页面入口猜测用户角色。
|
|
六 企业注册与入驻流程
|
|
|
|
[TABLE]
|
|
顺序 | 接口 | 预期结果
|
|
1 | POST /auth/sms/send | purpose 使用 company-register，获取企业注册验证码。
|
|
2 | POST /auth/company/register | 提交手机号、验证码、密码和企业基础资料；成功返回 COMPANY Token。
|
|
3 | GET /auth/me | 确认当前角色为 COMPANY。
|
|
4 | GET /companies/me/onboarding | 读取 UNVERIFIED、PENDING、REJECTED 或 VERIFIED，以及 missingFields、allowedActions。
|
|
5 | PUT /companies/me | 根据 missingFields 完善企业资料。
|
|
6 | POST /companies/me/verification | 提交企业认证材料。
|
|
7 | GET /companies/me/onboarding | 刷新聚合状态；前端按钮以 allowedActions 为准。
|
|
|
|
|
|
企业注册请求示例
|
|
POST /auth/company/register{ "phone": "19900000000", "code": "123456", "password": "符合密码策略的密码", "company": { "name": "示例科技有限公司", "industry": "互联网", "description": "企业简介", "website": "https://example.com", "address": "企业地址" }}
|
|
注意：客户端不能提交 userId、role、verified 或 passwordHash。注册响应中的 accessToken 和 refreshToken 按普通登录响应处理。
|
|
七 常用业务接口导航
|
|
|
|
[TABLE]
|
|
业务模块 | 常用接口 | 认证要求
|
|
公开岗位 | GET /jobs、GET /jobs/{jobId}、GET /jobs/search、GET /jobs/filters | 公开读取；具体以 OpenAPI security 定义为准
|
|
学生资料 | GET/PUT /profile/me、POST/GET/DELETE /profile/me/resume | STUDENT
|
|
求职流程 | 投递、面试、Offer、消息等接口 | 登录后按角色和资源归属校验
|
|
企业资料 | GET/PUT /companies/me | COMPANY
|
|
企业入驻 | GET /companies/me/onboarding、POST/GET /companies/me/verification | COMPANY
|
|
企业岗位 | POST/PUT /jobs 及发布关闭接口 | COMPANY；部分能力可能要求完成认证
|
|
管理员 | /admin 下审核、风控、举报等接口 | ADMIN
|
|
|
|
|
|
完整字段、枚举、必填项、响应结构和全部接口以运行时 OpenAPI 为唯一联调依据。本文只提供入口和使用顺序。
|
|
八 常见状态码处理
|
|
|
|
[TABLE]
|
|
HTTP | 含义 | 前端建议
|
|
400 | 参数错误、验证码错误或业务输入不合法 | 展示安全业务文案；字段错误定位到表单项。
|
|
401 | 未登录、Token 无效或过期 | 尝试一次刷新；失败后清理会话并回登录页。
|
|
403 | 角色不允许或无资源权限 | 展示无权限页面，不要循环刷新 Token。
|
|
404 | 资源不存在 | 展示资源不存在或返回列表页。
|
|
409 | 账号、状态或并发冲突 | 刷新当前数据后提示用户重新操作。
|
|
429 | 请求过于频繁 | 禁用按钮并显示倒计时，不要立即自动重试。
|
|
500 | 服务内部错误 | 显示通用错误，并上报 requestId。
|
|
503 | 依赖服务不可用或功能暂不可用 | 提示稍后重试，避免高频轮询。
|
|
|
|
|
|
九 前端联调检查清单
|
|
环境 Base URL 仅配置一次，接口路径中不重复拼接 /api/v1。
|
|
登录后 /auth/me 能返回正确角色，Authorization 头格式正确。
|
|
401 刷新流程不会无限循环，403 不触发刷新。
|
|
企业注册先发送 company-register 用途验证码，再调用企业注册接口。
|
|
企业页面从 /companies/me/onboarding 获取状态和 allowedActions，不在前端自行推导认证状态。
|
|
上传接口使用 multipart/form-data，不手动覆盖浏览器生成的 boundary。
|
|
报错时保留 HTTP 状态、业务 code、message、requestId 和请求时间；删除 Token、手机号、验证码及密码后再发给后端排查。
|
|
联调前先访问健康检查；健康为 UP 后再判断具体业务接口问题。
|
|
十 安全和协作约定
|
|
禁止在前端代码、Git、群聊截图或 Apifox 公共变量中保存数据库、Redis、RabbitMQ、Jenkins 密码。
|
|
禁止把 Access Token、Refresh Token、短信验证码和用户密码写入日志或错误上报。
|
|
接口字段调整由后端更新 OpenAPI，前端重新导入；不要以聊天记录替代接口定义。
|
|
需要后端排查时提供：环境、接口、方法、HTTP 状态、业务 code、requestId、发生时间和脱敏请求。
|