cloudflare-composition-root

Cloudflare 组合根

使用组合根：每个运行时入口点都将原始 Cloudflare 能力转换为应用自有依赖，组装服务并调用它们。内部代码接收端口，绝不接收 Env、原始绑定、框架服务定位器或绑定名称。

Cloudflare entrypoint
  → tracer + parsed configuration
  → binding adapters
  → exact service dependencies
  → application service
  → protocol projection

应用 ../coding-standards/SKILL.md 中的 TypeScript 契约、解析、错误、副作用和测试规范。如果实现方式不明确，请参阅 EXAMPLES.md 中的 Hono、WorkerEntrypoint、适配器和重构模板。

所有权

• **入口点适配器：**解析外部请求／事件，建立调用上下文，构造依赖，调用服务并映射其结果。
• **绑定适配器：**使用 KV、R2、D1、Durable Objects、Queues、服务绑定、Workflows 或其他外部能力实现应用自有端口。
• **应用服务：**负责一个用例的执行顺序、回退、重试和尽力而为策略。
• **领域模块：**负责纯值和不变量。
• **端口：**准确命名消费者所需的能力，不照搬 Cloudflare API。

原始平台值只能存在于组合根和绑定适配器中。绑定适配器只接收最小的平台能力，而不是整个 Env。

1. 梳理边界

检查仓库说明和受影响的：

• Hono 应用工厂、中间件顺序、路由注册和上下文类型；
• Worker、WorkerEntrypoint、Durable Object、Workflow、队列和定时入口点；
• Env 声明及相关绑定的所有用法；
• tracer 的创建、关联、错误报告和分离式工作的归属；
• 现有服务、适配器、端口、测试和架构检查。

从入口点到副作用和调用方可见结果，追踪每项受影响的行为。对于重构，在迁移之前记录当前的错误、重试、回退、序列化和追踪行为。

**完成标准：**已梳理所有受影响的入口点、绑定使用方、行为、生命周期、副作用、故障策略和现有测试接缝。

2. 设计应用自有依赖

根据消费者的需求定义契约：

/** Persistence capability required by document application services. */
export interface DocumentStore {
  /** Find one document by its domain ID. */
  find(id: DocumentId): Promise<Document | null>;
  /** Persist one valid document. */
  save(document: Document): Promise<void>;
}

/** Exact dependencies of the publish-document use case. */
export type PublishDocumentDependencies = Readonly<{
  documents: DocumentStore;
  clock: Clock;
  tracer: Tracer;
}>;

规则：

• 使用领域输入和已解析的输出，不使用原始键、字符串、请求对象或绑定选项。
• 只公开实际调用方所需的操作。
• 每个服务的依赖对象都应准确；绝不创建共享的万能依赖包，也不要把 Env 改名为 Dependencies。
• 在绑定适配器中处理平台序列化、键空间、分页令牌、TTL、元数据和输出解析。
• 由应用服务负责策略。适配器应足够准确地转换故障，以便服务区分可恢复情况、数据损坏和缺陷。
• 将 Tracer 注入会创建 span 的服务和适配器；不要将其添加到每个方法签名中。
• 只有在组合之后作用域确实会动态变化时，才添加应用自有工厂，例如身份验证后按账户构造。工厂不得暴露 Env 或原始绑定。

明确选择生命周期：

• 如果不可变适配器和服务所使用的绑定及 tracer 可安全地在并发调用间复用，则复用它们。
• 如果它们会保留请求级运行时对象或可变调用状态，则按调用构造。
• 将分离式工作交给明确的所有者，例如范围狭窄的后台任务端口；不要向内部泄漏 ExecutionContext。

**完成标准：**所有内部签名都使用应用／领域类型；每项操作和工厂都有当前调用方；依赖、tracer 和副作用的生命周期都有明确归属。

3. 构建或重构

新服务分支

1. 通过端口实现应用服务，不要导入 Hono 或 Cloudflare 运行时类型。
2. 为每个外部角色实现一个绑定适配器。为特定技术的实现指定明确名称，例如 WorkersKvDocumentStore。
3. 将协议相关内容保留在 HTTP、RPC、队列、Workflow 或定时任务适配器中。
4. 在每个提供该用例的入口点组装服务。

现有代码分支

1. 如果缺少依据，使用当前公共边界处的测试，保留调用方可见的行为。
2. 根据直接消费者已使用的操作，在该消费者处定义端口。
3. 在更改策略之前，先将现有原始绑定置于适配器之后。
4. 用端口替换直接消费者对原始依赖的使用。
5. 每次向外移动一层适配器构造。中间层可以传递类型化端口，但不得将端口和原始绑定永久并存为设计的一部分。
6. 拆分混合模块：策略移至应用服务；平台机制移至适配器；协议映射保留在入口点。
7. 移动最后一个调用方之后，移除过时的 Env 参数、工厂、通用包装器、重复的解析器／键构造器和兼容性重载。

不要仅为保持对称，就将重构范围扩大到无关绑定。

完成标准： 新代码已在每个服务入口完成组装，或每个迁移后的原始绑定都只会到达其适配器；行为和策略变更要么不存在，要么是明确要求并经过测试的。

4. 组装每个运行时表面

在每个组装根中，按顺序执行：

1. 解析配置和入口点属性。
2. 创建或获取 tracer。
3. 在调用被追踪的工作之前建立关联信息。
4. 将原始绑定包装为适配器，并在需要时注入 tracer。
5. 组装精确的服务依赖项。
6. 通过精简的协议适配器调用服务。
7. 将结果和安全错误映射到外部契约。

对于 Hono：

• 优先使用 createApp(dependencies)，以及闭包捕获精确依赖项的路由／中间件工厂。
• 注入根追踪中间件使用的 tracer，而不是在应用更深处创建无关的 tracer。
• 如果依赖项的作用域是单次调用，则让入口点提供一个范围狭窄的请求组装函数，并由该函数闭包捕获原始绑定；在建立关联信息后，从最早拥有该依赖项的中间件调用它。
• 在 Hono 变量中只存储精确的类型化能力。组装中间件和路由模块都不得通过 context.env 访问原始绑定。

对于 WorkerEntrypoint、Durable Objects、Workflows、队列和定时任务处理器，应将每个运行时构造器或处理器视为独立的组装根。不要假设某个运行表面的依赖关系图或生命周期适用于其他表面。

完成标准： 每个服务入口都建立追踪并构造完整的依赖关系图；没有任何内部模块获取运行时资源或读取绑定名称。

5. 验证边界

通过生产边界进行验证：

• 使用实现真实端口的小型记录型伪对象验证应用服务行为；
• 使用 Cloudflare 代表性本地运行时验证绑定适配器的序列化、解析和故障处理；
• 验证入口点组装以及外部结果／错误映射；
• 验证 span 名称、关联信息、安全属性和分离工作的所有权；
• 执行类型检查、针对性测试、架构检查以及仓库要求的验证。

使用项目的绑定名称和运行时类型搜索泄漏，例如：

rg 'Env|KVNamespace|R2Bucket|D1Database|DurableObjectNamespace|ExecutionContext' src

对每个匹配项进行分类：组装根、绑定适配器、不可避免的框架声明或违规项。还要搜索路由、服务、领域和能力模块中对 context.env 和绑定名称的直接访问。

完成标准： 每个原始平台引用都经过分类且符合许可；每个变更过的端口、适配器、服务、入口点、故障路径和生命周期都有验证依据；任何应用模块都不导入或接收 Cloudflare 运行时类型。