文档即代码：架构决策记录、API 文档与活文档

与代码共存的文档保持最新。Wiki 中的文档会过时。

架构决策记录（ADR）

ADR 记录架构决策的原因。

# ADR-001: 使用 PostgreSQL 作为主数据库

![文档即代码：架构决策记录、API 文档与活文档插图](https://images.pexels.com/photos/6964368/pexels-photo-6964368.jpeg?auto=compress&cs=tinysrgb&h=650&w=940)

## 状态
已接受

## 背景
我们需要一个数据库用于新的电商平台。需求包括：
- 订单处理的 ACID 事务
- 灵活产品属性的 JSON 支持
- 团队熟悉 SQL
- 托管服务可用性

## 决策
使用 PostgreSQL 15 作为主数据库。

## 后果
**正面：**
- 强 ACID 保证
- 优秀的 JSON/JSONB 支持
- 团队广泛熟悉
- 在 AWS RDS、Supabase、Neon 上可用托管服务

**负面：**
- 垂直扩展限制（通过只读副本解决）
- 需要模式迁移来变更

![文档即代码：架构决策记录、API 文档与活文档插图](https://images.pexels.com/photos/8636609/pexels-photo-8636609.jpeg?auto=compress&cs=tinysrgb&h=650&w=940)

## 考虑的替代方案
- MongoDB：因缺乏 ACID 事务被拒绝
- MySQL：考虑过，但 PostgreSQL 因更好的 JSON 支持被选中

# ADR 目录结构
docs/
  adr/
    001-use-postgresql.md
    002-use-event-driven-for-notifications.md
    003-adopt-trunk-based-development.md

OpenAPI 规范

# openapi.yaml
openapi: 3.1.0
info:
  title: 用户管理 API
  version: 1.0.0

paths:
  /users:
    get:
      summary: 列出用户
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: cursor
          in: query
          schema:
            type: string
      responses:
        '200':
          description: 用户列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'

使用 JSDoc/TSDoc 的代码文档

/**
 * 计算订单的运费。
 *
 * @param order - 要计算运费的订单
 * @param destination - 送货地址
 * @param options - 可选的运输偏好
 * @returns 以分为单位的计算运费
 * @throws {InvalidAddressError} 如果目标地址无效
 *
 * @example
 * ```typescript
 * const cost = await calculateShipping(order, {
 *   country: 'US',
 *   state: 'CA',
 *   zip: '94102'
 * });
 * console.log(`运费：${cost / 100}`);
 * ```
 */
export async function calculateShipping(
  order: Order,
  destination: Address,
  options?: ShippingOptions
): Promise<number> {
  // 实现
}

从代码生成文档

# TypeDoc 用于 TypeScript
npm install -D typedoc
npx typedoc --out docs/api src/index.ts

# 从代码注解生成 OpenAPI（NestJS）
npm install -D @nestjs/swagger

# 验证 OpenAPI 规范
npx @redocly/cli lint openapi.yaml

# 从 OpenAPI 生成客户端
npx openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o src/generated/api

Readme 最佳实践

# 项目名称

一句话描述。

## 快速开始

git clone && npm install && npm dev

## 前提条件
- Node.js 20+
- Docker（用于本地数据库）

## 开发
npm run dev     # 在 :3000 启动开发服务器
npm test        # 运行测试
npm run build   # 生产构建

## 架构
参见 docs/adr/ 了解架构决策。
API 文档：https://api.example.com/docs

文档即代码：版本控制、审查并与软件一起部署。