决策文档就是解这个问题的。叫 ADR、RFC 还是决策日志都无所谓，关键是在做选择的那一刻，把背景、备选方案和推理写下来。今年开始带开发团队之后，我对它的价值体会得更深了：它决定了团队拥有的是组织记忆，还是组织传说。

为什么值得花这个功夫

#

最直接的回报是不用把同一场架吵两遍。“API 版本策略不是已经定了吗？”只要决定了什么、为什么决定有清楚的记录，尘埃落定的问题就能保持落定，团队可以把力气花在执行上，而不是原路折返。

更安静的回报要过一段时间才显现。项目一跑就是几个月甚至几年，人来人往，最后留下的只有代码——代码能告诉你决定了“什么”，却永远不会告诉你“为什么”。决策文档保存的正是推理本身：当时存在的约束、被否掉的备选方案、拍板的人是谁。新人得到的是上下文而不是传说；跨团队的决策因为所有人都能看到权衡的因素而更容易获得真正的认同；决策者和参与者都写着名字，后续落实也就有了明确的主人。

什么时候写

#

不是每个决策都配得上一份文档。我会在决策属于以下情况时动笔：

• 回头代价高的 — 技术栈选择（框架、数据库、云服务商）、架构模式（微服务还是单体、事件驱动还是请求-响应）、第三方供应商选型、安全与合规方案
• 影响长期存在的 — 外部系统依赖的 API 契约、跨多个服务的数据模型、对既定模式的破坏性变更
• 需要跨团队的 — 需要多个团队或非技术相关方认同的事项、资源分配和优先级取舍
• Spike（技术预研）的结论 — 限时调研结束后，趁发现和决定还没蒸发，赶紧落成文档

反过来，容易撤销的决定、团队内部的实现细节、对自己范围之外几乎没有影响的选择，就别走形式了。没人需要的文档只是作业。

生命周期

#

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│    草稿     │ ──► │    评审     │ ──► │    批准     │ ──► │    实施     │
│    提议     │     │   反馈      │     │    接受     │     │    完成     │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │   否决/     │
                    │   取代      │
                    └─────────────┘

作者起草问题和候选方案，相关方进行评审——整套流程的价值主要就在评审这一步，因为假设被挑战、盲点被暴露都发生在这里。然后由决策者（通常是技术负责人、架构师或产品负责人）拍板，团队实施；实施中如果现实逼着改了方案，文档也要跟着更新。有的文档死在评审里，有的日后随情况变化被取代——两种都要清楚标记，一份过期却还挂着“已批准”的文档，是给下一个发现它的人挖的坑。

什么样的文档才值得读

#

从问题开始，而不是从你心仪的方案开始。我们在解决什么？为什么是现在？什么都不做会怎样？如果大家对问题本身都没有共识，讨论方案就是演戏。

然后给出真正的备选项——哪怕你已有强烈倾向，也至少写两三个。每个选项配上简短描述、优缺点、粗略的工作量估算（T 恤尺码就够用：S/M/L/XL），以及风险和应对办法。把落选方案写下来，未来的读者才能明白胜者为什么胜出。

把取舍大声说出来。“我们选择上市速度，放弃架构纯粹性。”“我们接受运维复杂度上升，换取更好的扩展性。”“我们把开发者体验放在原始性能之前。”这样的句子对未来读者的帮助，超过几页纸的分析。

让讨论落在具体的东西上：展示方案实现样子的代码片段、系统交互图、指向 Spike 概念验证的链接。抽象的讨论只会产出抽象的决定。

最后，给它一个期限：什么时候必须定下来，谁在什么时间前要给意见，拖着不决会卡住什么。没有期限的决策会永远飘着。

示例：架构决策记录（ADR）

#

下面是一个实际的决策文档示例：

# ADR-001: API Authentication Strategy

**Status:** Accepted
**Date:** 2024-11-15
**Decision Maker:** Sarah Chen (Platform Architect)
**Contributors:** Backend Team, Security Team, Mobile Team

## Context

Our public API currently uses API keys for authentication. As we expand to
support third-party integrations and mobile apps, we need a more robust
authentication mechanism that supports:
- Token expiration and refresh
- Scoped permissions
- User-level authentication (not just service-level)

## Decision

We will implement OAuth 2.0 with JWT tokens for API authentication.

## Options Considered

### Option 1: OAuth 2.0 with JWT (Recommended)
**Description:** Industry-standard protocol with self-contained tokens

| Pros | Cons |
|------|------|
| Industry standard, well-documented | More complex initial implementation |
| Self-contained tokens reduce database lookups | Tokens cannot be revoked instantly |
| Broad library support | Requires refresh token management |

**Effort:** Medium (2-3 sprints)

### Option 2: Session-based Authentication
**Description:** Traditional server-side sessions with cookies

| Pros | Cons |
|------|------|
| Simple to implement | Not suitable for mobile apps |
| Easy to revoke sessions | Requires sticky sessions or shared session store |
| Familiar to most developers | Doesn't scale as well |

**Effort:** Small (1 sprint)

### Option 3: Custom Token System
**Description:** Build our own token-based authentication

| Pros | Cons |
|------|------|
| Fully customizable | Reinventing the wheel |
| No external dependencies | Security risks from custom implementation |

**Effort:** Large (4+ sprints)

## Consequences

- Mobile team can implement standard OAuth flows
- We'll need to set up a token refresh mechanism
- API documentation will need updates for OAuth flows
- Existing API key users will need a migration path (6-month deprecation)

## References

- [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749)
- Internal spike document: [Authentication Options Spike](/spikes/auth-spike-2024)
- Security team review: SEC-2024-042

一份可以直接拿走的模板

#

把它当起点，按团队需要往下删：

问题描述

#

我们要解决什么问题？为什么重要？不采取行动的代价是什么？

背景

#

提供上下文、历史和相关细节。链接到相关文档、过去的决策或Spike结果。

约束条件

#

所有方案必须遵守哪些限制或要求？

• 预算约束
• 时间线要求
• 技术约束（现有系统、技能储备）
• 合规或安全要求

考虑的方案

#

建议

#

说明推荐的选项，并总结在约束和取舍条件下为什么它是最佳选择。

决定

#

做出决定后记录最终决策。如果与建议不同，说明原因。

后果

#

这个决策有什么影响？需要哪些后续工作？

行动项

#

参考资料

#

相关文档、外部资源、Spike结果或过去决策的链接。

让习惯扎根

#

文档放在固定的地方——仓库里的专用文件夹也好，Wiki 空间也好——找不到的决策等于不存在。保持轻量：一份要写好几天的文档根本不会被写出来。在代码注释、提交信息和 PR 里引用决策文档，让“为什么”一直贴着“是什么”。决策被取代时别删旧文档，标记为已取代并链接到新决策，历史本身就是价值。另外，在回顾会上时不时翻翻过去的决策：哪些经受住了考验，哪些换成今天你会做得不一样。

失败的方式也同样好预测。分析瘫痪：定个期限，用手头的信息做决定，大多数决策以后都能再议。橡皮图章式评审从来提不出真正的批评，只加流程不加价值。写了却从未落地的孤儿文档，比没有文档更糟。细节过多也是病：文档管“为什么”和“是什么”，不管“怎么做”，实现细节属于技术规格书。还有，当有人不同意时，把反对意见也写进去——决定也许照旧，但那条异议恰恰是一年后某个人最需要的上下文。

从你的下一个重要决策开始吧。写得糙一点没关系，流程边用边磨。每一场因为有人直接读了 ADR 而没开成的“我们当初为什么选 X”会议，都是还给团队的时间。

延伸阅读

#

本站相关文章：

• 理解敏捷软件开发中的Spike - 在做重大决策前用 Spike 收集信息
• 回顾会：反馈循环的力量 - 把审视过去的决策纳入持续改进
• API规划 - 把决策文档的思路用在 API 设计上
• 用GitHub做项目管理 - 让决策文档和代码放在一起

外部资源：

• Documenting Architecture Decisions - Michael Nygard - 让 ADR 流行起来的那篇经典博文
• ADR GitHub Organization - 架构决策记录的工具、模板和示例
• Design Docs at Google - Google 的设计文档实践
• RFC Process at Rust - Rust 语言完善的 RFC 流程
• Spotify’s Decision Record Template - Spotify 关于何时写 ADR 的思考

做B2B SaaS，租户架构这个问题迟早会找上门，通常就是某个大客户问“我们的数据能不能和别人分开放”的那一天。这种讨论我经历过不止一次。答案基本就两个：给每个客户独立的实例（单租户，多实例），或者让所有人共享一个实例（多租户，单实例）。没有哪个是“正确答案”，只是坏起来的方式不一样。

基础设施设计

#

单租户，多实例

#

这条路的吸引力就在“隔离”二字，几乎所有好处都由此而来。每个客户的数据都在自己独立的环境里，安全审查和合规谈判会轻松很多。一次糟糕的部署或一个吃资源的任务，只会影响一个客户，而不是全部。每个实例可以独立扩容、调优、定制；资源专用，性能不会因为隔壁租户在跑什么而波动。维护也能按客户逐个安排，停机影响小而可控。定价合理的话，还能让基础设施成本对上每个租户的实际用量。

代价是：所有东西你都要运维N份。资源开销不断累积，实例之间的配置慢慢漂移，让整个集群的版本和数据保持一致本身就成了一个项目。扩容、隔离、成本管理的问题不会消失，只会成倍增加。

多租户，单实例

#

它是默认选项不是没有原因的：一套部署、一个要备份的数据库、生产环境只有一个版本。资源利用率高，运维简单，所有客户同时拿到更新和安全补丁。

难点是共享的另一面。一个租户用得猛，所有人的性能都会被拖累；按客户定制的空间有限；数据隔离不再靠基础设施，而是落在你的应用代码里，一个bug就可能变成跨租户的数据泄露。扩容瓶颈一来就是所有客户一起受影响，维护也要更小心，因为再也没有“只影响这一个客户”的爆炸半径了。

延伸阅读：SaaS 方案中的多实例与多租户架构

多租户 vs 多实例

#

这个选择也常被说成“多租户 vs 多实例”，其实是同一件事从另一面看。“租户”说的是客户：一套软件有几个客户在共用。“实例”说的是部署：你跑了几套软件。单租户产品就是每个客户一套的多实例部署，多租户产品通常是大家共用的单实例。所以有人要“多实例”，意思就是要单租户。

实际上它更像一条光谱，而不是二选一，真正的决定大多落在数据库上。最共享的一端，是所有客户的数据行放在同一批表里，每行带一个 tenant_id 列，每条查询都按它过滤。运行成本最低，也最容易出错。往前一步，是在共享数据库里给每个客户单独一个 schema：隔离更干净，也能按客户备份，代价是每次迁移都要按 schema 的数量跑一遍。再往前，应用共享，但每个客户有自己的数据库：不用给每个客户跑一整套技术栈，数据隔离也够强，是很常见的折中。另一端就是完全的单租户，应用和数据库都是独享的。AWS 的 SaaS 指南把两端叫作 silo（筒仓）和 pool（池），两者混用叫 bridge（桥接），向客户的安全团队解释你的架构时，这套说法挺好用。

单租户 vs 多租户一览

#

什么时候用哪种

#

除非有具体原因把你推开，否则就选多租户。客户多、每家付得不多、用户自己注册、团队小到三十套环境就能把人拖垮，这些情况下，多租户都是正确的默认选项。

单租户只在少数几种情况下值回它的开销。医疗、金融、政府类客户常常要求数据物理隔离，或者必须放在某个国家，而在安全审查里，独享实例是对此最简单也最老实的回答。如果只有几家签企业合同的大客户，他们负担得起自己那一套，往往也期待有一套。再就是客户需要自己的发布节奏、锁定某个版本，或者深度定制的时候，分开的实例就不再是开销，而成了你卖的产品的一部分。

大多数团队最后两种都用：绝大多数客户用多租户产品，少数需要并且愿意付钱的客户，作为企业版给独享实例。只要多租户版本从第一天起处处带着租户 ID，以后把某个客户单独迁到自己的数据库，就是一次迁移，而不是重写。

让多租户的隔离更难被打破

#

多租户里最让人睡不着的 bug，是忘了加租户过滤的查询。它不会报错，只会悄悄把别人的数据返回给你，而代码评审也不可能每次都抓到。如果你用的是 Postgres，行级安全（RLS）可以把这道检查挪到数据库里，这样就算查询忘了过滤，也只能看到当前客户的数据行：

ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON invoices
    USING (tenant_id = current_setting('app.tenant_id')::uuid);

然后每个请求在事务里用 SET LOCAL app.tenant_id = '…' 设置租户。这样连接池里的连接不会把上一个客户的 ID 带进下一个请求，忘了设置租户的请求会直接报错，而不是拿到数据。有两个坑：应用要用一个不是表所有者的角色连接，因为除非再加上 FORCE ROW LEVEL SECURITY，表的所有者会绕过这些策略；也永远不要用超级用户连接，超级用户无论如何都会绕过。

单租户从哪里开始？

#

真要走单租户，工具决定它是“可以管”还是一场慢动作灾难。三十套环境，靠手是管不过来的。

核心是容器加基础设施即代码。Docker把应用打包成对每个租户都完全一致的形态，Kubernetes负责这一堆实例的部署和扩缩容；用Terraform、Pulumi或AWS CloudFormation把一个租户的完整技术栈定义成代码，第31个客户的开通就是一个PR，而不是一个报废的周末。如果你更贴近虚拟机的世界，Ansible、Chef、Puppet这类配置管理工具可以承担同样的角色。CI/CD流水线（Jenkins、GitLab CI/CD）在这里比平时更重要，因为每次发布都要在所有实例上滚动完成，不能靠人盯。

再往后就看产品形态了。有些工作负载可以直接用无服务器（AWS Lambda、Azure Functions）把服务器这一层整个抹掉。Amazon RDS、Azure SQL Database这类托管数据库，能把你从“每个租户手动维护一个库”的苦役里救出来。有了一个集群之后，监控（Prometheus、Grafana、New Relic）就不再是可选项：哪个实例不舒服，你得赶在客户开口之前知道。身份这块交给Auth0或Okta这样的IAM服务，就不用每个租户重造一遍认证。不管你用什么语言，多半都有面向SaaS的框架或库能帮你省掉一部分这类底层活儿；托管方面，AWS、Azure、Google Cloud Platform这些大厂云都能轻松接住。

别想着第一天就把清单买齐。先上容器和IaC，租户多起来再加监控和IAM，剩下的，让真实的痛点来决定。

长话短说

#

单租户，也就是多实例，是每个客户一套独立的应用和数据库：隔离强、能按客户控制，代价是要运维一整个集群。多租户是大家共用一套：便宜、简单，隔离靠代码保证。大多数产品应该从多租户起步，处处带上租户 ID 并让数据库来强制执行，再给少数需要并愿意付钱的客户提供独享实例。如果真要跑单租户，让它保持可控的关键是容器和基础设施即代码。