Routa API契约实战：用api-contract.yaml让Web与桌面端永远保持一致

【免费下载链接】routaWorkspace-first multi-agent coordination platform for AI development, with shared Specs, Kanban orchestration, and MCP/ACP/ A2A support across web and desktop.项目地址https://gitcode.com/gh_mirrors/ro/routa点击查看免费下载Routa 是一个 Workspace-first 的 AI 多智能体开发平台它同时提供Web 端Next.js和桌面端Tauri Rust两种运行形态。两种形态、两套后端却必须对用户呈现完全一致的行为——靠什么保证答案就在仓库根目录的那份 api-contract.yaml一份 OpenAPI 3.1 契约文件定义了 158 个 API 端点是 Web 与桌面端 API 的单一事实来源Single Source of Truth。这篇文章带你走一遍 Routa API 契约的实战流程契约长什么样、如何自动验证双端一致性、以及新增接口时的标准动作。为什么双后端 API 一致性这么难想象一下同一个看板界面在浏览器里由 Next.js 服务端口 3000驱动在桌面客户端里由 Rust/Axum 服务端口 3210驱动。如果没有契约约束时间一长两边必然漂移Web 端加了PATCH /api/workspaces/{id}桌面端忘了同步桌面用户更新工作区标题就 404两端返回的字段名不一致一个叫taskId一个叫task_id前端组件时好时坏错误码一个返回 400、一个返回 500用户看到的报错信息对不上Routa 的解法写在架构决策记录 ADR-0001 双后端语义对等 中Web 与桌面是一个产品的两个运行时形态必须共享同一套领域词汇workspace、session、task、kanban board并暴露由api-contract.yaml统一治理的 API 形状。api-contract.yaml 长什么样契约的核心结构打开 api-contract.yaml头部声明就说明了它的地位Single source of truth for the Routa.js dual-backend API. Both the Next.js backend (src/app/api/) and the Rust backend (crates/routa-server/) MUST implement all endpoints defined here.契约声明了两个服务地址api-contract.yamlservers: - url: http://localhost:3000 description: Next.js backend (dev) - url: http://localhost:3210 description: Rust backend (desktop)共享的领域枚举两端说同一种语言契约的components.schemas部分定义了共享数据模型。比如任务状态api-contract.yamlTaskStatus: type: string enum: [PENDING, IN_PROGRESS, REVIEW_REQUIRED, COMPLETED, NEEDS_FIX, BLOCKED, CANCELLED]无论 Next.js 还是 Rust返回的任务状态都必须是这 7 个值之一。前端只需实现一次状态渲染两端通用。端点定义路径、参数、响应一个不落以健康检查为例api-contract.yaml/api/health: get: operationId: getHealth responses: 200: schema: type: object required: [status, timestamp]再看创建智能体api-contract.yaml——请求体明确要求name和rolerole必须引用共享的AgentRole枚举ROUTA / CRAFTER / GATE / DEVELOPER成功返回201并包含agentId与agent对象。契约把入参要求什么、成功返回什么、失败返回什么全部写死两个后端照着实现即可。整个契约共覆盖 158 个端点横跨 agents、tasks、kanban、notes、workspaces、sessions、shared-sessions、ACP、MCP、A2A、git、github、codebases 等模块你可以直接通读 api-contract.yaml 的paths部分。契约如何自动守门3 层验证命令写契约只是第一步Routa 的关键设计是契约不是摆设它被自动化验证反复执行。第 1 层静态 Schema 校验不需要启动服务npm run api:schema:validate对应脚本 validate-openapi-schema.ts 会做 7 项静态检查所有$ref能否解析、operationId是否唯一、响应 Schema 能否被 AJV 编译、枚举是否非空等等。契约文件本身写得对不对这一步就能拦住。第 2 层三端路由对账Parity Checknpm run api:check这是最有意思的一步。check-api-parity.ts 会从三个来源提取路由清单并逐一比对api-contract.yaml中声明的端点Next.js 文件系统路由扫描src/app/api/下的route.tssrc/app/api/ 共 245 个文件Rust 路由扫描crates/routa-server/src/api/crates/routa-server/src/api/下的.rs文件任何一端缺失契约里定义的端点或私自带了一个契约里没有的端点都会被精确报出——契约里有、Rust 里没有和Next.js 多写了一个是两种不同的漂移都会失败。第 3 层行为测试同一套测试打两个后端前两层是静态的第三层是真枪实弹。tests/api-contract/run.ts 实现了一套与后端无关的测试套件覆盖 workspaces、agents、tasks、notes、sessions、skills、schema-validation 七大场景npm run api:test:nextjs # 打到 http://localhost:3000 npm run api:test:rust # 打到 http://localhost:3210同一套断言、两个 BASE_URL。如果 Rust 端的行为和 Next.js 端出现任何偏差响应结构、状态码、负向路径的报错测试就会在其中一个后端上失败。其中 test-schema-validation.ts 更进一步对真实响应用契约里声明的 JSON Schema 做逐字段校验覆盖 create → read → delete 全链路。验证命令验证什么需要启动服务npm run api:schema:validate契约文件自身合法性❌npm run api:check契约 vs Next.js vs Rust 路由一致性❌npm run api:test:nextjs/api:test:rust双端真实行为对等✅新增一个 API 端点4 步标准流程Routa 遵循**契约优先Contract First**原则先改契约再写代码。docs/fitness/api-contract.md 中规定的新端点流程 在 api-contract.yaml 中定义端点路径、方法、参数、请求/响应 Schema 在 Next.js 中实现src/app/api/下新建路由 在 Rust 中实现crates/routa-server/src/api/下新增对应 handler✅ 运行npm run api:check验证一致性并在 rust-api-test.md 端点矩阵中登记测试条目修改现有端点更严格必须先评估是否为breaking change若是则需要版本化或废弃旧端点、提供迁移文档、并在 PR 中明确标注——契约原则里写着Breaking Changes 禁止除非有迁移计划docs/fitness/api-contract.md。契约被破坏时会发生什么Fitness 门禁自动拦截Routa 把 API 契约检查纳入了 fitness工程适应度体系作为硬门禁hard gatedocs/fitness/api-contract.mdopenapi_schema_valid与api_parity_check两个指标均为hard_gate: true通过阈值 100 分——也就是说Schema 校验或路由对账任何一处不过整个检查直接失败docs/fitness/rust-api-test.mdapi_contract维度权重 10除npm run api:check外还挂了 Rust 侧的端到端测试cargo test -p routa-server --test rust_api_end_to_end并按端点 × 方法 × 成功/负向/回归路径三层逐条登记 VERIFIED 证据换句话说没有契约覆盖的 API 进不了主干。CI 里api:schema:validateapi:check两道闸门跑不过代码就无法合并。动手看看克隆仓库跑一遍git clone https://gitcode.com/gh_mirrors/ro/routa cd routa npm install npm run api:schema:validate # 静态校验契约 npm run api:check # 三端路由对账前两条命令无需启动任何服务几秒钟就能看到契约与两个后端的对账结果。想体验行为层测试再分别启动 Next.jsnpm run dev或 Rustcargo run -p routa-server执行对应的npm run api:test:*即可。小结3 个值得借鉴的设计单一事实来源158 个端点全部声明在 api-contract.yaml 中两个后端是契约的实现者不是契约的作者分层验证静态 Schema → 路由对账 → 行为测试成本递增、可信度递增且前两层零依赖即可运行门禁化契约检查不是建议而是 fitness 体系里的硬门槛破坏契约的代码过不了 CI对多形态产品Web / 桌面 / CLI来说API 契约文件 自动化对账是把永远保持一致从一句口号变成一条npm run api:check命令的最实际路径。赞分享【免费下载链接】routaWorkspace-first multi-agent coordination platform for AI development, with shared Specs, Kanban orchestration, and MCP/ACP/ A2A support across web and desktop.项目地址https://gitcode.com/gh_mirrors/ro/routa点击查看免费下载相关推荐5分钟快速上手Windows系统完美安装苹果苹方字体终极指南5分钟快速上手Windows系统完美安装苹果苹方字体终极指南 还在为Windows系统缺乏优雅中文显示效果而烦恼吗PingFangSC苹方字体作为苹果公司精前端插上 U 盘就能开播my-tv 免费电视直播软件装上就用、零门槛换台插上 U 盘就能开播my tv 免费电视直播软件装上就用、零门槛换台 你想让老电视看直播可大多点播软件要么要注册账号、要么有会员墙而你要的只是一台开机就音视频直播TREK 的 trek/shared用 Zod 契约包统一前后端 API 类型的单一事实源实战TREK 的 trek/shared用 Zod 契约包统一前后端 API 类型的单一事实源实战 trek/shared 是 TREK自托管旅行规划应用后端前端MCP 服务AI 应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考