framework

Croco Framework 是一个基于 Node.js 的 TypeScript 框架，将 AWS Lambda 和 API Gateway 视为一等公民。其 README 将其定义为“强主见 (opinionated)”的框架，旨在解决大规模项目中难以维持架构一致性的问题，因此明确划分了基于角色的包边界。 包被分为六类角色：Kernel（框架运行时基础：framework-context, framework-module）、Contracts（独立于提供者和运行时的领域/协议合约：repository-core, protocols-rest, telemetry-api）、Plugins（合约的实现与环境绑定：tx-drizzle, transports-http, preset-node）、Application（应用自有模块与 composition root）、Profiles（经过验证的插件/模块组合：presentation-preset）以及 Tooling（构建、代码生成、测试、CLI）。Kernel 和 Contracts 不依赖于具体的 Plugin，角色定义标准参考 docs/package-catalog.json 中的 packageRoles。 该框架的特点在于区分了 Host、Transport 和 Build Target。Host 拥有 Node 进程/服务器、Lambda 调用或 Workers fetch 的生命周期（如 preset-node, preset-lambda, preset-cloudflare）；Transport 执行 HTTP、GraphQL、RPC 等协议界面；Build Target 则是声明入口点、输出目录、模块格式和捆绑限制的 Tooling 合约。一个 Host 可以绑定多个 Transport 回调。 在功能方面，它提供 DDD 领域事件 (events-core) 与 RegisterEventHandler、Unit of Work 模式的 Transactional 事务 (tx-core, 通过 AsyncLocalStorage 传播)、基于 RFC 7807 的 Problem 响应详细化 (problems-core)、重试与恢复装饰器 (Retryable, Recover — retry-core)、生成 OpenTelemetry Span 的 Trace (telemetry-api) 以及基于装饰器的 DI 容器 (framework-context)。REST 控制器通过 Controller/Get/Post 装饰器定义，并使用 createApp 和 createLambdaHost 配置 Lambda 处理程序。 针对 SaaS 领域，该框架提供了计费、权益 (entitlement)、额度 (credit)、计量 (metering) 和客户状态等合约包，以及 Polar, Clerk, Drizzle, PostHog, QStash 等提供者集成包。其原则是不将失败隐藏在普通 Error 或静默回退中，而是通过 Problem, retry, timeout, circuit breaker, idempotency 和详尽处理 (exhaustive handling) 进行建模。 启动路径是通过 npx create-croco-app@latest 进行脚手架搭建（例如 --goal saas-api），并使用 pnpm demo:smoke 在无需外部凭据的情况下验证生成的 REST 合约和内存中 SaaS 流程；在 examples/quick-start-lambda 中可以通过 pnpm dev 运行包含 Auth 和 Metering 的示例。 根据 README，其目录追踪了 120 个公开包（排除 2 个私有包），并通过 1.0 spine 将 18 个包固定在 release-critical 兼容范围内。其中 10 个为 production-ready，8 个为 beta，alpha/WIP 和 deprecated 为 0。成熟度和分组信息是由存储库元数据生成的产出物，若出现偏差，docs:catalog:check 将失败。基准测试在 benchmarks/ 目录下管理方法论、基准线和阈值，并在专用 workflow 中基于最近 5 次的 green evidence 作为阻塞门 (blocking gate) 运行，但 README 中未给出具体性能数值。与 NestJS、Hono、tRPC 的对比表明确表示是为了说明设计上的差异，而非性能数值或竞争对手评估。