用途:面向编写消费 Forze 框架代码的开发者,指导正确使用 ExecutionContext 及各基础设施端口。分层架构中依赖向内流动:Domain 为纯业务逻辑,Application 只导入 Domain,Infrastructure 提供实现契约的适配器,Interface 通过上下文调用用例;用例与领域模型不得导入适配器或基础设施包。
主要能力:通过 ExecutionContext 按逻辑 spec 解析基础设施。常用方法包括 dep(key, route)、doc_query(spec)、doc_command(spec)、cache(spec)、counter(spec)、storage(spec)、search_query(spec)、txmanager(route),另有 embeddings_provider、hub_search_query、federated_search_query、分布式锁、租户解析等。没有便捷方法的键用 ctx.dep(DepKey, route=spec.name)(ctx, spec)。
使用方式:用例继承 Usecase[Args, R],持有 ExecutionContext 并实现 main(args)->R,从 self.ctx 解析端口。读用 doc_query,写用 doc_command。查询 DSL 支持 $fields、$and、$or,字段快捷写法与 $eq、$neq、$gt、$gte、$lt、$lte、$in、$nin、$null、$empty、$superset、$subset、$overlaps、$disjoint 等操作符及排序。事务用 async with self.ctx.transaction(TxRoute.DEFAULT),嵌套复用活动事务,副作用用 defer_after_commit 或 run_after_commit_or_now。计数器与存储需传 CounterSpec(name=...)、StorageSpec(name=...)。身份在边界绑定,用例可读但不应自行 bind_call。
限制与注意:doc_read/doc_write、ctx.search、ctx.counter("name")、ctx.storage("bucket")、ctx.workflow_command(...) 均已过时或不存在;transaction() 必须传已注册路由;不要在同一作用域混用不兼容事务后端。反模式包括在用例中导入适配器、领域导入上层、用例中写原始 SQL/ORM、手工构造 ExecutionContext(应通过 runtime.get_context() 或 FastAPI ctx_dep 获取)。