企业官网建设流程全解析

2011 年 10 月，Google 工程师 Steve Yegge 在 Google+ 上误发布了一篇批评 Google 平台战略的内部长文。这篇文章后来被技术圈称为 “Steve Yegge's Google Platform rant”，是软件工程历史上被讨论最多的一篇内部吐槽。文章没有抱怨界面设计，也没有讨论数据中心选址，而是围绕一个非常工程化的问题展开：Google 当时拥有业内最强大的内部基础设施，从分布式文件系统到大规模集群调度器，为什么始终没有像 Amazon 那样，把这些能力沉淀为外部开发者可以依赖的平台。

这篇 rant 到今天仍然有价值，是因为它讲的不是某一家公司的八卦，而是 API 设计、服务化架构、平台工程和团队协作方式的基本问题。很多团队在建设内部平台时犯的错误，在 2011 年已经被 Steve Yegge 用很直白的语言点名过。下面先还原事件和文章核心逻辑，再拆解平台、API 契约、dogfooding 三个概念，然后给出一套可以用于评估自身服务化程度的验收清单，最后用一个最小的 API-first 下单服务示例，说明怎样把吐槽变成可落地的工程方法。

1. 先还原那场争论：一次误发如何变成公开案例

1.1 事件背景：内部长文被意外发布到 Google+

2011 年 10 月，Steve Yegge 是 Google 的一名工程师，也是当时有影响力的技术写作者，长期在个人博客上讨论编程语言和软件工程。他在公司内网写下一篇关于 Google 平台战略的长文，批评 Google 在对外平台建设上相比 Amazon 明显落后。文章发布时被设置为不公开，但在实际操作中误发到了公开的 Google+ 信息流，随后被大量转发。

原文是一篇类似“内部宣讲”的长文，不是严谨的白皮书，观点带有情绪和夸张，也夹杂大量个人经验。但它包含的信息量非常大：他对比了 Google 和 Amazon 两家公司在“把内部能力变成外部平台”上的差距，指出 Amazon 通过强制 API 化，把一个电商公司变成了云计算的奠基者；而 Google 虽然内部有 Borg、Bigtable、MapReduce 这类后来影响整个业界的系统，却长期没有把它们变成外部开发者可以消费的服务。

这一段从事件本身看是事故，从技术传播的角度看反而成了一次高曝光度的架构公开课。后续很多关于“平台思维”和“API 优先”的讨论，都会引用这篇文章作为起点。

1.2 核心矛盾：基础设施强不等于平台能力强

这里要区分两个概念。基础设施强，指的是团队内部有高性能的存储、计算、调度、消息等组件，内部工程效率很高。平台能力强，指的是外部开发者或者公司内部其他业务团队，能够稳定地、自助地基于这些能力构建自己的产品。

Steve Yegge 的核心观点是：Google 属于前者，Amazon 属于后者。Amazon 当年为了让电商业务内部不再互相写死，强制所有团队之间只能通过服务接口通信。这个决定在当时看起来像管理命令，实际上把公司业务切成了一组边界清晰的服务，后来这些服务逐步收敛成 AWS 对外提供。

而 Google 的很多内部系统在设计时只考虑“服务自己”，没有把接口做成对外部开发者友好的抽象，也没有形成稳定的 API 契约。于是内部很强，外部很难用。这就是“基础设施强，平台能力弱”的典型形态。

1.3 为什么十多年后仍然值得读

2011 年到现在，技术栈已经变了很多，但问题没有消失。今天的微服务、Service Mesh、API 网关、内部开发者平台（IDP），本质上都在解决同一个问题：怎么让一个复杂组织里的能力被其他团队可靠地、自助地、低成本地使用。如果只把服务拆细，却没有把接口契约、版本策略、权限模型和对外语义设计好，得到的只是“分布式单体”，而不是平台。

技术选型会过时，API 设计原则不会。重读这篇 rant，相当于用一次真实的组织案例，理解 API-first 为什么是服务化架构的前提。它不只是开发规范，而是一种组织协作方式。

2. 三个关键概念：平台、API 契约与 dogfooding

2.1 平台是“别人能在上面构建业务”的基础层

先讲通俗含义。一个系统如果只能被自己的开发团队使用，它叫内部工具；如果其他团队或者外部开发者能稳定地、在不需要了解内部实现的情况下构建业务，它才叫平台。

技术定义上，平台是提供一组稳定接口和运行环境，让第三方在其上构建、运行和交付应用的基础设施。这里的第三方，可以是公司内其他部门，也可以是外部开发者。

用 rant 里的对比来说，Amazon 把电商内部能力 API 化之后，外部开发者在 AWS 上申请计算资源、存储资源、消息队列和服务，不需要知道 Amazon 内部有多少台机器、机房在哪里、调度系统叫什么名字。接口就是边界，边界之外全部隐藏。

容易误解的地方在于：很多人认为“把系统做成通用模块”就是平台。其实模块复用解决的是代码层面的复用，平台解决的是业务能力层面的复用。模块要调用方在构建期集成，平台只需要调用方在运行时通过 API 消费。两者对团队的耦合程度完全不同。模块耦合在版本号上，平台耦合在接口语义上。

2.2 Amazon 的 API 指令：用强约束逼出服务化组织

Steve Yegge 在 rant 里重点讲了一个细节：Amazon CEO 在 2002 年左右下达了一条内部指令，要求所有团队的数据和功能必须通过服务接口暴露，团队之间只能通过网络接口通信，不能直接读其他团队数据库，不能通过共享内存或后门链接，所有接口都必须按“未来可以对外暴露”的标准设计，否则会被解雇。

这条指令的本质是：用管理层强约束，打破团队之间靠数据库共享、代码互相调用形成的隐式耦合。一旦通信方式被限制为“只能通过 API”，团队就必须把边界定义清楚，把数据结构、接口语义、错误处理、版本策略都显式化。没有人能悄悄修改一张表就影响全局，因为别人看到的是接口，不是数据库。

这个约束放到今天是微服务拆分的基本原则：服务之间只能通过 API 通信，禁止直连数据库、禁止共享缓存、禁止私有 JAR 到处引用。如果团队没有这类硬性约束，只靠大家自觉来制定边界，最后一定会退回到点对点耦合。很多服务化项目失败的起点，就是没有把“只能通过 API”这条规则真正落地。

2.3 dogfooding 是验收机制，不是口号

“吃自己的狗粮”在技术圈常被说成“自家东西自家先用”。它真正的工程含义是：一个平台如果连自己内部的核心业务都不愿意用，就不可能有外部开发者愿意稳定使用。

原因很简单。内部是离问题最近、反馈最快、业务量最真实的一批用户。如果平台能在内部业务的真实流量、真实异常、真实峰值下稳定运行，外部用户面对未知场景时至少有一份经过验证的基线。反过来，如果平台只是内部团队为展示而造，不参与真实业务，接口在边界情况下的设计缺陷就不会暴露。

在工程落地时，dogfooding 不是“顺便用一个接口”，而是“平台团队自身就是第一个付费用户”。接口文档、错误提示、限流策略、权限申请流程，都必须先被自己的真实业务使用，才能迭代到可对外程度。这一点在今天的云产品里仍然成立：很多云厂商要求内部业务优先使用自己的云产品，保证新能力有真实用户反馈。

3. 从 rant 反推一套服务化架构验收清单

3.1 服务是否具备“可被外部消费”的第一印象

判断一个服务是不是“平台化服务”，可以问三个问题：新业务团队能不能自助申请权限、查询接口文档、完成联调？接口是否提供稳定的版本？调用方是否需要知道服务内部的数据表结构？

如果三个问题的答案都不理想，说明当前服务还停留在“内部接口”阶段。内部接口往往依赖调用方对自己代码的理解，文档不全、版本随改随发、错误语义模糊。外部消费方一旦接入，所有不明确的点都会变成工单。

推荐的做法是，把一个内部服务想象成要交给陌生团队使用：文档里能不能仅凭接口描述调通？错误码是不是有统一规范？有没有沙箱环境？这些是平台化的起点。平台不是把网关架起来再说的结果，而是从接口设计第一天就要回答的问题。

3.2 接口契约：版本、兼容性与语义

接口契约不是“定义几个字段”，而是双方的长期约定。至少要覆盖以下内容：

• 请求和响应的数据结构，字段含义和取值范围。
• 错误码体系，包括业务错误、参数错误、鉴权错误、限流错误、系统错误。
• 版本策略，例如 URL 路径带 v1、v2，还是请求头带版本号；破坏性变更如何发布。
• 兼容性规则，例如只允许新增字段，不允许删除字段或改变已有字段语义。

常见做法是用 OpenAPI（Swagger）描述契约，用契约生成文档和客户端 SDK。契约文件本身要进代码仓库、参与版本管理、接受 review。只要契约稳定，实现方内部无论怎么重构，调用方都不会受影响。

这里有一个关键点：兼容性不只是“字段还在不在”，还包括语义是否变化。一个字段从“必填”改为“选填”，或者从“订单金额含税”改为“订单金额不含税”，都算破坏性变更。这类问题无法靠自动化工具完全发现，必须由契约 review 兜底。

3.3 服务治理：注册发现、限流、权限、可观测性

只有接口没有治理，平台在真实流量下会迅速失序。服务化架构至少要具备四类能力。

一是注册发现。服务实例动态变化时，调用方要能通过注册中心找到可用实例，而不是把 IP 写死在配置里。

二是限流与配额。一个平台面向多个消费方，必须能按调用方限流、按接口限流，防止某个消费方的异常流量拖垮整个服务。

三是权限与认证。接口要区分匿名、内部服务、外部应用、管理端等身份，使用统一的鉴权机制，至少要支持 API Key、内部服务账号，必要时上 OAuth2。

四是可观测性。每个接口都要有监控指标、访问日志、追踪信息、错误率统计。没有可观测性的平台，出问题时只能靠调用方反复重试来定位。

组件名只作示意，落地前要确认与自身技术栈的兼容性。先选稳定的核心组件，再逐步扩展。

3.4 团队边界：API 契约比代码复用更值得作为边界

微服务拆分时，很多团队会把“代码能不能复用”作为边界判断标准。结果是一旦发现公共逻辑，就抽一个公共模块，所有服务引用同一个 JAR 或同一个 npm 包，最后公共模块一变，所有服务一起受影响。

从 API-first 的角度看，团队边界应该以“能不能独立交付和独立演进”为标准。两个服务之间如果只需要通过网络 API 交互，就可以分开；如果必须共享一个私有包，说明边界还没设计清楚。公共逻辑确实可以放入共享 SDK，但共享 SDK 要按公共契约管理，版本升级要有策略，不能允许每个服务随意锁定或随意升级。

这一条是在组织层面复现 rant 的核心：平台化的前提，是团队之间通过显式接口协作，而不是通过隐式实现共享协作。

4. 最小案例：用 API-first 把“下单能力”改造成可复用服务

4.1 场景拆解

假设有两套业务：一套是电商小程序，一套是线下门店收银系统，都需要创建订单、查询物流、取消订单。用传统写法，两套业务各自实现一套订单逻辑，数据库各建各的表，支付回调后两边各更新一份状态，会出现对账不一致。

平台化思路是：把“订单”抽象为一个订单服务，提供创建订单、查询订单、取消订单、接收支付回调四个接口。两套业务都通过 API 调用这个服务，订单数据只有一份。

这个例子在真实公司里对应的是：一个业务能力被多个业务端复用，且必须保证数据一致性。API 契约就是这些业务端之间的“宪法”。先不写实现代码，先写契约，这是 API-first 最核心的差别。

4.2 先写 OpenAPI 契约，再写实现

用 OpenAPI 描述创建订单接口，一个最小示例：

openapi: 3.0.0 info: title: Order Service version: 1.0.0 paths: /v1/orders: post: summary: 创建订单 operationId: createOrder requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateOrderRequest' responses: '201': description: 创建成功 content: application/json: schema: $ref: '#/components/schemas/Order' '400': description: 参数错误 content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: 限流 content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CreateOrderRequest: type: object required: - buyerId - skuId - quantity properties: buyerId: type: string description: 买家编号 skuId: type: string description: 商品编号 quantity: type: integer minimum: 1 description: 购买数量 remark: type: string description: 备注，可选 Order: type: object properties: orderId: type: string status: type: string enum: - CREATED - PAID - SHIPPED - CANCELED Error: type: object properties: code: type: string message: type: string

契约里值得注意的点：状态用枚举而不是开放字符串，避免调用方理解产生歧义；错误码统一，避免每个团队各自定义一套；请求必填字段明确；创建成功返回 201 而不是 200，语义更准确；429 是限流场景的统一响应。

写完契约后，服务端按契约实现，客户端按契约生成 SDK。这样任何一端改接口定义，都会在代码生成和联调阶段暴露问题，而不是上线后才爆雷。

4.3 内部调用与外部开放共用同一份契约

平台化落地时，最容易出现的问题是内部调用和外部开放各有一套接口。内部用老接口、外部用新接口，两个版本逻辑漂移，最后内部接口成为技术债。

正确的做法是：内部核心业务优先调用设计为可对外开放的同一份契约服务。即使短期内不对外，接口也按外部标准设计。这样内部流量承担了 dogfooding 的职责，真实业务能把错误处理、限流、并发、数据一致性问题提前暴露出来。

例如，电商小程序的后端服务调用订单服务时，走 HTTPS + API Key + 业务上下文；外部第三方应用未来接入时，走完全相同的接口，只是在网关层补充额外的认证和配额。网关可以加，但不能改变服务本身的契约语义。

4.4 三阶段落地路径

平台化不是一蹴而就，建议分三个阶段。

第一阶段：内部服务契约化。把现有业务改造为对内部团队开放的 API，文档、版本、错误码统一，内部调用全部走 API。

第二阶段：半开放。在 API 网关后面提供沙箱环境，引入少量内部非核心业务或合作伙伴试用，收集真实反馈，调整契约。

第三阶段：对外发布。补充计费、配额、审计、SLA、公告和版本弃用策略。只有前两个阶段跑稳了，对外才不至于被真实流量打崩。

学习环境里可以只做第一阶段，验证 API-first 流程；生产环境必须把二、三阶段的治理能力补齐。

5. 平台建设中的常见误区与排查清单

5.1 误区一：把内网接口网关化就算开放平台

现象：团队把已有内网接口挂到网关，加一层鉴权，就宣布平台上线。外部开发者接入后发现：接口文档不完整，错误码五花八门，字段名是内部缩写，接口经常随内部重构而变化。

原因：网关只是流量入口，不是平台。平台要解决的是契约、稳定性和自助性，网关解决的是路由和统一认证。接口本身的设计如果没有按外部消费标准来做，加多少层代理都不能改变它的脆弱性。

解决方式：先按 3.2 整理的契约清单逐项补齐，再开放。不要用网关替代接口设计。

5.2 误区二：脱离真实业务，先造“通用能力”

现象：平台团队成立后，第一件事是设计一套“通用的权限系统”“通用的消息中心”“通用的用户中心”，追求大而全，结果做出来没人用。

原因：通用能力必须在真实业务里提炼。没有具体业务方，设计者无法判断边界条件、并发量、数据模型和错误语义，做出来的抽象要么过度设计，要么覆盖不了真实需求。

解决方式：平台团队要绑定至少一个核心业务方，从一到两个真实场景提炼能力。先满足一个业务，再复制到第二个业务。第二、三个业务带来的抽象才是可靠的。

5.3 误区三：只给接口，不给契约、版本和弃用策略

现象：服务提供了接口，但没有版本号；调用方升级时，服务端直接改字段语义；旧版本下线没有任何公告和过渡期。整个调用方社区长期处在“跟着服务端改代码”的节奏里。

原因：平台的价值在于稳定。接口一旦被多个调用方依赖，就不再只是服务端自己的代码，而是一份多方契约。没有版本和兼容性策略，契约形同虚设。

解决方式：约定至少保留一个旧版本，破坏性变更必须给出迁移方案和过渡期。版本策略要写进开发规范，在 Code Review 中检查。

5.4 平台化改造排查清单

在排查“为什么平台没人用”或者“为什么平台经常出问题”时，按顺序检查：

这张表可以直接拿来做团队内部的服务化答辩检查表。每次平台改造迭代后，都应该把这六项重新过一遍。

6. 从 rant 里带走什么：给工程团队的落地建议

6.1 个人项目与小型团队先做什么

个人项目或三五人团队，不必一开始就引入微服务和大量治理组件。先做三件事：

第一，把项目中的核心能力设计为稳定的模块接口，内部调用通过明确的函数签名或本地服务接口完成，不要通过共享数据库表隐式耦合。

第二，如果项目需要对外提供数据能力，从第一版就维护一份契约文件，哪怕只是 OpenAPI 或简单的 Markdown 文档，也比什么都没有强。

第三，强迫自己作为第一个调用方使用自己设计的接口。如果自己在使用时都觉得别扭，说明接口语义有问题。

6.2 中大型团队如何推进契约治理

中大型团队推进 API-first，建议按以下顺序：

先确定契约管理方式。把 OpenAPI 文件放入独立仓库，服务端和客户端都从契约生成代码，避免手写两套定义。

再定义接口规范。统一错误码结构、时间格式、分页格式、幂等等规则。这些看起来琐碎，却是多个服务能否被统一消费的基础。

然后建立验收流程。新增或变更接口必须经过契约 review，检查版本策略、兼容性、错误处理、安全性和可观测性配套。

最后用工具落地。引入 API 文档平台、网关、契约测试，把规范从文档变成自动校验项。

6.3 最值得练习的一课：把自己变成第一个用户

整篇 rant 最值得记住的工程判断是：平台不是别人造出来的词，而是“自己是否愿意用”的结果。如果一个 API 连自己的真实业务都不在用，它就没有被验证过；没有被验证过的接口，不能称为平台能力。

练习的方法是：每次写完一个服务接口，不看隐藏的内部实现，只按文档试着调用它。用另一个进程、另一个账号、另一个网络环境，完全模拟陌生调用方。这个简单的习惯，能暴露文档缺失、鉴权混乱、错误语义不清、版本不兼容等大多数平台问题。

更进一步，可以把自己的服务部署到与生产兼容的测试环境，让另一个团队按文档完成一次无协助接入。全程记录被问过哪些问题、改过哪些配置、绕过哪些坑，这些问题就是平台化的改进清单。

延伸阅读方面，可以继续研究 API 网关设计、OpenAPI 规范、内部开发者平台（IDP）、契约测试和服务网格相关资料。这些主题都在解决 rant 里指出的同一类问题：如何让复杂系统的能力被稳定地、大规模地复用。理解了 2011 年那场争论，再看这些技术方案，会更清楚它们到底在解决什么。