API Contract 治理

SpringOpen 当前处于 V1.0 前开发阶段，尚未对历史版本承诺二进制或数据库兼容。仓库只维护当前代码定义的 contract，不保留旧类、旧字段、旧路由、旧配置或旧迁移桥接。

核心原则

当前代码、构建配置和 Liquibase 基线是唯一事实来源。
contract 调整必须在同一功能簇内同步后端、Admin / App / PC、OpenAPI、正式文档、权限、i18n 和迁移。
不通过 deprecated 包装、旧 DTO 访问器、双路由、双读双写或历史 jar 比较维持开发期兼容。
所有 REST API 路由带主版本，统一使用 /api/v{major}/{domain}/**。
后台管理 API 使用 /api/v{major}/admin/{domain}/**。
HTTP 状态表达传输层结果，业务成功以 Result.code == 200 为准。
入参使用 DTO，出参使用 VO，不直接暴露 Entity。

路由结构

普通 API：

text

/api/v{major}/{domain}/{resources}

后台 API：

text

/api/v{major}/admin/{domain}/{resources}

后端从 ApiRoutes.API_V1、ApiRoutes.ADMIN_V1 和 owning domain 常量派生路由。路由中的版本用于清晰组织 contract；V1.0 前不表示对旧实现作兼容承诺。

兼容 OpenAI、Claude 等外部协议的网关可以在框架路由后保留协议自身版本，例如 /api/v1/ai/gateway/claude/v1/messages。框架 API 版本和外部协议版本各自表达自己的边界。

Contract 变更

开发期允许直接执行以下调整：

删除或重命名 Java 类型、方法、字段和枚举值。
删除或重命名 REST 路由、请求字段和响应字段。
调整数据库表、列、索引、约束和 seed。
删除旧配置名、旧环境变量和兼容解析分支。

每次调整必须同时完成：

更新所有后端调用方与模块依赖。
更新 Admin、App、PC 的 API client、类型、页面和路由。
更新 OpenAPI、错误码、权限码和三语 i18n。
更新 owning module 的 Liquibase schema / seed 基线。
更新正式文档和对应 .ai/modules / .ai/starters 当前事实。
运行与改动范围匹配的构建、测试和仓库检查。

禁止只改公共 API 后用旧兼容层压住编译错误；编译错误应直接暴露并推动所有调用方迁移到当前 contract。

请求与响应

普通 JSON Controller 使用项目统一响应：

java

ResponseEntity<?> detail(@PathVariable Long id)

文件、流式和跳转等非 JSON 响应按场景返回：

java

ResponseEntity<Resource>
ResponseEntity<byte[]>
ResponseEntity<SseEmitter>

字段规则：

Java DTO / VO 使用 camelCase。
数据库列使用 snake_case。
查询、排序和过滤字段必须经过后端白名单归一化。
展示元数据优先由后端按 locale 返回，前端不复制业务翻译表。

Open Platform

开放平台同样以当前 contract 为准：

scope、签名算法、防重放、计量、配额、成本和账单在同一功能簇内一起调整。
canonical string、Header、错误码和 SDK 示例必须同步更新。
未到 V1.0 不维护历史开放 API 兼容分支；部署方只能使用与当前版本一致的 SDK 和文档。

数据库基线

每个实体归 owning module 的 schema 迁移，初始化数据归同模块 seed 迁移。
开发期基线按当前模型直接整理，不保留旧列、旧表、旧 checksum 或跳过式 precondition。
验证以干净数据库首跑和当前版本二次启动幂等为准。
不提供旧 tag 数据库原地升级桥接；需要保留的测试数据由开发者按当前 schema 重新准备。

当前门禁

bash

./mvnw test -DskipITs -DskipFrontend -Dsurefire.failIfNoSpecifiedTests=false
pnpm -C views/admin typecheck
pnpm -C views/pc typecheck
pnpm -C views/app build:h5
./.ai/scripts/check all
git diff --check

涉及应用装配或迁移时，还必须用干净数据库启动当前应用并再次启动，确认 Liquibase 无新增执行、无重复 changeSet。

V1.0 冻结

V1.0 对外发布前再建立第一份稳定 contract 基线。届时若需要 Java 二进制兼容、REST 废弃周期或数据库升级窗口，必须新增 ADR，明确基线版本、检查工具、支持周期和破坏性变更策略；不得把 V0.x 历史重新引入当前代码。

API Contract 治理 ​

核心原则 ​

路由结构 ​

Contract 变更 ​

请求与响应 ​

Open Platform ​

数据库基线 ​

当前门禁 ​

V1.0 冻结 ​