架构评审清单

// 好的模块边界
// apps/api/src/
// ├── modules/
// │   ├── orders/
// │   │   ├── orders.router.ts      # 路由层
// │   │   ├── orders.service.ts     # 业务层
// │   │   ├── orders.repository.ts  # 数据层
// │   │   └── orders.types.ts       # 类型定义
// │   └── users/
// │       └── ...
// └── shared/
//     ├── middleware/               # 共享中间件
//     └── utils/                    # 共享工具
 
// orders.router.ts - 路由层只做路由装配
import { Hono } from 'hono'
import { OrdersService } from './orders.service'
 
export const ordersRouter = new Hono()
 
ordersRouter.post('/', async (c) => {
  const body = await c.req.json()
  const service = new OrdersService(c.env)
  const order = await service.create(body)
  return c.json(order, 201)
})
 
// orders.service.ts - 业务层处理业务逻辑
export class OrdersService {
  private env: Env
 
  constructor(env: Env) {
    this.env = env
  }
 
  async create(input: CreateOrderInput): Promise<Order> {
    // 业务逻辑：校验库存、计算价格、创建订单
    // 不直接操作数据库，通过 repository
  }
}
 
// orders.repository.ts - 数据层只操作数据库
export class OrdersRepository {
  private db: D1Database
 
  constructor(db: D1Database) {
    this.db = db
  }
 
  async findById(id: string): Promise<Order | null> {
    return this.db.prepare('SELECT * FROM orders WHERE id = ?')
      .bind(id)
      .first()
  }
}

// 坏的依赖关系：循环依赖
// orders.service.ts 依赖 users.service.ts
// users.service.ts 依赖 orders.service.ts
 
// 解决方法：引入事件或接口层
// 1. 事件驱动
import { EventBus } from '../shared/event-bus'
 
export class OrdersService {
  async create(input: CreateOrderInput) {
    const order = await this.createOrder(input)
 
    // 发布事件，而不是直接调用 UserService
    await this.eventBus.publish('order.created', {
      orderId: order.id,
      userId: order.userId
    })
  }
}
 
// 2. 接口层
interface UserNotifier {
  notifyOrderCreated(userId: string, orderId: string): Promise<void>
}
 
export class OrdersService {
  private notifier: UserNotifier
 
  constructor(notifier: UserNotifier) {
    this.notifier = notifier
  }
 
  async create(input: CreateOrderInput) {
    const order = await this.createOrder(input)
    await this.notifier.notifyOrderCreated(order.userId, order.id)
  }
}

// 数据所有权：每个实体只有一个服务可以写入
 
// orders-service - 拥有订单数据
export class OrdersService {
  async createOrder(input: CreateOrderInput) {
    // 只有这个服务可以写入 orders 表
    return this.db.prepare('INSERT INTO orders ...')
  }
 
  async getOrder(id: string) {
    return this.db.prepare('SELECT * FROM orders WHERE id = ?')
  }
}
 
// users-service - 拥有用户数据
export class UsersService {
  async getUser(id: string) {
    return this.db.prepare('SELECT * FROM users WHERE id = ?')
  }
}
 
// 跨服务查询：通过 API 调用，而不是直接访问数据库
export class OrdersService {
  async getOrderWithUser(orderId: string) {
    const order = await this.getOrder(orderId)
 
    // 通过 API 调用获取用户信息
    const user = await this.httpClient.get(`/users/${order.userId}`)
 
    return { ...order, user }
  }
}

## 决策：选择 Cloudflare D1 作为主数据库
 
### 背景
- 应用部署在 Cloudflare Workers
- 需要关系型数据库存储订单、用户数据
- 预期数据量：< 1000 万行
 
### 考虑的方案
1. **Cloudflare D1**
   - 优势：与 Workers 深度集成、零运维、按用量计费
   - 劣势：单region、只读副本有限
   - 成本：$0.50/GB/月
 
2. **PlanetScale (MySQL)**
   - 优势：功能丰富、多 region
   - 劣势：需要额外运维、冷启动延迟
   - 成本：$39/月起
 
3. **Supabase (PostgreSQL)**
   - 优势：功能丰富、实时订阅
   - 劣势：冷启动延迟、需要管理连接池
   - 成本：$25/月起
 
### 决策
选择 D1。
 
### 理由
1. 应用已在 Workers，D1 集成最紧密
2. 数据量 < 1000 万行，D1 容量足够
3. 不需要多 region 写入
4. 成本最低
5. 团队有 SQLite 经验
 
### 退出成本
如果未来需要多 region，可以迁移到 PlanetScale，
数据导出为 SQL 文件即可。

// Cloudflare Workers 自动水平扩展
// 但需要注意：无状态设计
 
import { Hono } from 'hono'
 
const app = new Hono()
 
// 好的设计：无状态
app.get('/orders/:id', async (c) => {
  const orderId = c.req.param('id')
 
  // 从 D1 读取，任何实例都能处理
  const order = await c.env.DB.prepare('SELECT * FROM orders WHERE id = ?')
    .bind(orderId)
    .first()
 
  return c.json(order)
})
 
// 坏的设计：有状态（内存缓存）
const cache = new Map() // 每个 Worker 实例有自己的缓存
 
app.get('/users/:id', async (c) => {
  const userId = c.req.param('id')
 
  // 不同实例的缓存不共享
  if (cache.has(userId)) {
    return c.json(cache.get(userId))
  }
 
  const user = await c.env.DB.prepare('SELECT * FROM users WHERE id = ?')
    .bind(userId)
    .first()
 
  cache.set(userId, user) // 只在这个实例有效
  return c.json(user)
})
 
// 正确做法：使用 KV 或 Cache API
app.get('/users/:id', async (c) => {
  const userId = c.req.param('id')
 
  // 使用 KV 作为缓存
  const cacheKey = `user:${userId}`
  let user = await c.env.KV.get(cacheKey, 'json')
 
  if (!user) {
    user = await c.env.DB.prepare('SELECT * FROM users WHERE id = ?')
      .bind(userId)
      .first()
 
    // 缓存 5 分钟
    await c.env.KV.put(cacheKey, JSON.stringify(user), {
      expirationTtl: 300
    })
  }
 
  return c.json(user)
})

import { Hono } from 'hono'
 
const app = new Hono()
 
// 带重试的外部调用
async function fetchWithRetry(
  url: string,
  options: RequestInit,
  maxRetries = 3
): Promise<Response> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, {
        ...options,
        signal: AbortSignal.timeout(5000) // 5 秒超时
      })
 
      if (response.ok) {
        return response
      }
 
      // 5xx 错误才重试
      if (response.status >= 500) {
        throw new Error(`HTTP ${response.status}`)
      }
 
      // 4xx 错误不重试
      return response
    } catch (error) {
      if (i === maxRetries - 1) {
        throw error
      }
 
      // 指数退避：1s, 2s, 4s
      const delay = Math.pow(2, i) * 1000
      await new Promise(resolve => setTimeout(resolve, delay))
    }
  }
 
  throw new Error('Max retries exceeded')
}
 
// 降级策略
app.get('/products/recommendations', async (c) => {
  try {
    // 尝试调用推荐服务
    const recommendations = await fetchWithRetry(
      'https://recommendation-service.internal/api/recommend'
    )
    return c.json(await recommendations.json())
  } catch (error) {
    // 降级：返回热门推荐
    console.error('Recommendation service failed:', error)
 
    const fallback = await c.env.KV.get('recommendations:fallback', 'json')
    return c.json(fallback || [])
  }
})