/tags/api-governance/ Recent content in api-governance on Hugo -- gohugo.io en Wed, 06 May 2026 10:00:00 +0800 /posts/openapi-contract-first-workflow/ Wed, 06 May 2026 10:00:00 +0800 /posts/openapi-contract-first-workflow/ Contract First（也叫 API First）的理念并不新鲜：在写任何代码之前，先把 API 的形状定义清楚，让前后端、移动端、第三方消费者都从这份约定出发并行开发。但这套思路在很多团队里一直停留在 PPT，原因往往不是不认可，而是落地成本比想象中高——谁来写 spec、风格谁来管、变更谁来通知、breaking change 谁来拦，每一个问题都可能让一个团队悄悄退回 Code First。 这篇是我自己在 Spring Boot + 前端栈（TypeScript / React 或 Angular）里反复试错后整理的实践笔记，关注的是怎么让 Contract First 跑起来，并尽量持续不退回老路，而不是介绍 OpenAPI 语法。 如果你只想看 JVM 团队怎么把 contract 做成可执行验证（Spring Cloud Contract、WireMock、CI Quality Gates），可以直接跳到《Java 项目怎么做 contract testing：一次 Spring Cloud Contract 实践》。本文聚焦在 spec、协作和治理这一层。 为什么坚持 Contract First？ Code First 在小项目里没什么问题：后端先写完接口，把 Swagger 文档丢出去，前端照着对接。问题出现在团队和系统变大之后： 文档总是滞后——后端改了实现却忘了同步 Swagger 注解，前端按旧文档调用，联调阶段才发现 前端只能等——接口没写完，前端只能压时间或自己 mock，等真接口出来再返工 跨团队沟通成本高——每加一个消费方（移动端、第三方、内部 BFF），就要重新解释一遍接口 breaking change 靠口头同步——后端"顺手"改了字段类型，下游调用才发现问题 Contract First 的核心价值，是让 API 契约成为单一事实来源（single source of truth）。spec 不是事后的文档，而是开发的起点：所有人从同一份 YAML 出发，前后端可以并行，breaking change 最好显式审批。我倾向把它理解成一种"用工程约束代替口头沟通"的解耦机制，对微服务、电商、支付这种跨团队跨系统的场景尤其有价值。