API 契约与版本兼容性

本文档定义 youlai-admin 的 API 契约规范，以及各后端实现的差异说明。

核心原则

版本化

v{主版本}.{次版本}.{修订版本}

• 主版本：不兼容的变更（删除字段、改变语义）
• 次版本：向后兼容的新增（新增可选字段）
• 修订版本：Bug 修复

向后兼容

允许：新增可选字段、新增枚举值、新增接口 禁止：删除必需字段、改变字段类型、修改必填规则

统一响应格式

{ "code": "00000", "message": "成功", "data": {} }

详见 API 快速开始

各后端差异

维度	Java	NestJS	Go	Django	PHP	ASP.NET
基础路径	/api/v1	/api/v1	/api/v1	/api/v1	/api/v1	/api/v1
认证	JWT+Security	JWT+Guard	JWT+Casbin	JWT	JWT	JWT
分页	pageNum/pageSize	同左	page/perPage	同左	同左	同左
Swagger	Knife4j /doc.html	Swagger /api	Swagger	Swagger	Swagger	Swagger
多租户	✅ 完整	❌	❌	❌	❌	❌
SSE	✅	✅	✅	✅	✅	✅

接口差异

认证接口

所有后端的登录/登出/刷新 Token 接口完全一致。

用户管理

功能	Java	其他后端差异
用户列表	支持 deptId 筛选	部分后端可能不支持
重置密码	返回新密码明文	可能返回空或加密串

文件上传

差异点	说明
大小限制	各后端默认不同，需查看配置
存储方式	本地/OSS/S3，各后端可配置
允许类型	默认 jpg/png/gif/pdf/doc/xls

版本兼容策略

客户端适配

// 检查后端版本
const checkVersion = (version: string) => {
  const [major] = version.split('.')
  if (parseInt(major) >= 2) {
    // 处理 v2 新增字段
  }
}

字段处理

// 安全读取可选字段
const name = user.nickname ?? user.username ?? '未知'