示例与指引

本页是仓库内可运行示例的正式导航入口。现在唯一的示例代码主入口是项目根目录 examples/，而不是 docs/examples/，也不再是早期的单文件 demo。

推荐心智： 先写装饰器式业务代码，用 @application 声明入口方法，再用 @configure(...) 附着启动配置， 然后直接调用 main() 完成运行时装配。
延伸阅读： 快速开始、构建与运行、 参数系统指南、测试与验证

推荐阅读顺序

1. examples/minimal_app/ —— 最短公开入口
2. examples/controller_service_inject/ —— @service、@controller 与 Inject() 的业务分层
3. examples/middleware_and_module/ —— 什么时候值得在入口方法之上再显式引入 @module
4. examples/parameter_handling/ —— Path、Query、Body 的控制器方法参数绑定
5. examples/testing_flow/ —— 不启动真实服务进程时通过 main.get_asgi_app() 做测试

示例地图

示例	主要讲什么	运行命令	源码
examples/minimal_app/	使用 @application + @configure(...) + main() 组织最小应用	python -m examples.minimal_app	在 GitHub 查看
examples/controller_service_inject/	service/controller 分层与类型驱动的 Inject() 注入	python -m examples.controller_service_inject	在 GitHub 查看
examples/middleware_and_module/	模块边界归属与中间件管线扩展	python -m examples.middleware_and_module	在 GitHub 查看
examples/parameter_handling/	控制器方法上的 Path、Query、Body	python -m examples.parameter_handling	在 GitHub 查看
examples/testing_flow/	基于公开 API 的 ASGI 测试流	python -m pytest examples/testing_flow/test_app.py -q	在 GitHub 查看
examples/static_files_and_spa/	声明式 StaticFiles 挂载 + SPA 回退（引擎中立）	python -m examples.static_files_and_spa	在 GitHub 查看

为什么要重构示例

旧示例容易把开发者带回“手工注册 app”的思路。新的示例集刻意把 Cullinan 当前想表达的概念放在最前面：

• 业务装饰器优先，而不是显式 app 装配优先
• 先用入口方法表达默认入口
• 当结构和归属重要时，再显式引入 @module 表达运行时边界
• 类型契约清晰时，默认优先使用 Inject()
• 把参数绑定写在控制器方法上，而不是先教底层 request plumbing
• 通过公开 API 做测试，而不是依赖内部启动捷径

补充说明

• 根目录 examples/README.md 会同步这条学习链路，方便直接看仓库的开发者。
• 也可以直接从 examples/ 浏览已入库的示例源码。
• tests/integration/test_examples_public_guides.py 会对当前维护的示例做 smoke test。
• 如果你第一次接触 Cullinan，建议先完成 examples/minimal_app/，再进入 examples/controller_service_inject/。