API 参考

说明（v0.90）：核心模块已重新组织。新的 API 结构请参阅 依赖注入指南 和 导入迁移指南。

本页概览 Cullinan 的公开 API，并明确哪些 API 属于推荐路径、哪些属于高级集成能力。

如果你还没建立推荐学习路径： 请先看 应用构建 和 框架语义。
如果你要进入高级运行时内部机制： 请转到 运行时与扩展。

API 分层

推荐默认 API

• cullinan —— 常规业务项目应优先使用的顶层应用 API：
• 启动入口：@application、configure(...)，然后直接调用入口方法（例如 main()）
• 声明入口：@service、@controller、@module（高级边界）、路由装饰器
• 注入 / 参数：Inject、InjectByName、Path、Query、Body 等
• 框架心智：装饰器优先的业务代码、组件发现、IoC/DI 装配，以及带有热插拔语义的模块边界

高级集成 API

• cullinan.application —— 面向维护者与框架感知型集成的高级公开应用语义（Application、Runtime、module、run、get_asgi_app）
• cullinan.transport.adapter —— 服务器集成（WebAdapter、TornadoAdapter、ASGIAdapter）
• cullinan.web.gateway —— 请求 / 响应 / dispatcher 契约
• cullinan.core —— 低层容器与生命周期原语

这些高级模块都不是默认的应用开发心智模型。常规业务代码应停留在顶层 cullinan API，以及框架自身的装饰器 / DI / 模块边界语义上，而不是转向低层运行时编排或具体服务器适配器。

对于常规应用，请优先使用顶层 cullinan API。高级模块应显式从对应子模块导入，这样在代码评审、IDE 补全和 onboarding 文档中都能更清楚地看到边界。

v0.94 Phase A 的冻结口径使用各包的 __all__ 作为可审阅导出契约：

• cullinan.__all__ —— 常规应用应使用的启动、声明与请求处理 API
• cullinan.application.__all__ —— 高级 application/runtime 辅助入口，包括 run() 与 get_asgi_app()
• cullinan.web.__all__ / cullinan.core.__all__ —— 显式业务 Web 面与容器/生命周期面

未出现在对应 __all__ 列表中的符号应视为私有实现细节。带 _ 前缀的兼容性导出可以继续存在，但不属于默认业务公开稳定承诺。

v0.90+ 新增：参数系统

参数系统提供类型安全的请求参数处理。详见 参数系统指南。

cullinan.web.params (v0.90a4+)

符号	类型	说明
Param	类	参数基类
Path	类	URL 路径参数标记
Query	类	查询字符串参数标记
Body	类	请求体参数标记
Header	类	HTTP 请求头参数标记
File	类	文件上传参数标记
RawBody	类	原始请求体，使用 bytes = RawBody() (v0.90a5+)
UNSET	哨兵	表示未设置的哨兵值
TypeConverter	类	类型转换工具
Auto	类	自动类型推断工具
AutoType	类	用于签名的自动类型标记
DynamicBody	类	动态请求体容器
SafeAccessor	类	链式安全访问器
EMPTY	哨兵	空值哨兵
ParamValidator	类	参数校验工具
ValidationError	异常	校验错误
ModelResolver	类	dataclass 模型解析器
ModelError	异常	模型解析错误
ParamResolver	类	参数解析编排器
ResolveError	异常	参数解析错误

cullinan.web.params (v0.90a5+)

符号	类型	说明
FileInfo	类	文件元数据容器
FileList	类	多文件容器
field_validator	装饰器	Dataclass 字段校验器
validated_dataclass	装饰器	自动校验的 dataclass
FieldValidationError	异常	字段校验错误
Response	装饰器	响应模型装饰器
ResponseModel	类	响应模型定义
ResponseSerializer	类	响应序列化工具
serialize_response	函数	便捷序列化函数
get_response_models	函数	获取函数的响应模型

cullinan.web.params.model_handlers (v0.90a5+)

可插拔模型处理器架构，用于第三方库集成。

符号	类型	说明
ModelHandler	类	模型处理器抽象基类
ModelHandlerError	异常	模型处理器错误
ModelHandlerRegistry	类	模型处理器注册表
DataclassHandler	类	内置 dataclass 处理器
PydanticHandler	类	可选 Pydantic 处理器（安装后可用）
get_model_handler_registry()	函数	获取全局处理器注册表
reset_model_handler_registry()	函数	重置注册表（测试用）

cullinan.codec

符号	类型	说明
BodyCodec	类	请求体编解码器抽象类
ResponseCodec	类	响应编码器抽象类
JsonBodyCodec	类	JSON 请求体解码器
JsonResponseCodec	类	JSON 响应编码器
FormBodyCodec	类	Form 请求体解码器
CodecRegistry	类	Codec 注册表
get_codec_registry()	函数	获取全局 Codec 注册表
reset_codec_registry()	函数	重置 Codec 注册表（测试用）
DecodeError	异常	解码错误
EncodeError	异常	编码错误
CodecError	异常	编解码错误基类

cullinan.web.middleware（新增）

符号	类型	说明
BodyDecoderMiddleware	类	自动请求体解码中间件
get_decoded_body()	函数	获取已解码的请求体
set_decoded_body()	函数	设置已解码的请求体（测试用）

公共符号与签名（建议结构）

每个模块建议按以下结构列出公共符号：

• 模块路径，例如：cullinan.web.controller
• 简要说明：模块的主要职责与使用场景
• 公有类与函数列表（示例）：
• @controller(...) — 控制器装饰器，负责自动注册控制器与路由
• @get_api(url=..., query_params=..., body_params=..., headers=...) — GET 接口装饰器
• @post_api(url=..., body_params=..., headers=...) — POST 接口装饰器
• Inject, InjectByName — 属性/构造器注入标记

完整 API 参考可以通过自动生成脚本或手工整理的方式填充上述结构。

v0.95 新增（Track A 内部重构）

新增公共 API 符号

符号	位置	类型	说明
ScopeViolationError	cullinan.core.exceptions	异常（LifecycleError 子类）	当单例/原型组件传递依赖请求作用域组件时抛出。携带 dependency_chain、origin_name、violating_component。
format_scope_violation_error	cullinan.core.diagnostics	函数	根据依赖链、起源、违规组件渲染人类可读的作用域违规描述。
strict_private_injection	ApplicationContext.__init__	关键字参数	为 True 时，注入标记扫描器跳过单下划线（_xxx）属性。默认 False。
strict_lifecycle	ApplicationContext.__init__	关键字参数	为 True 时，非关键生命周期钩子失败（on_startup/on_shutdown）以 LifecycleError 抛出。默认 False。
skip_private	get_injection_markers	关键字参数	为 True 时，扫描标记时跳过单下划线前缀属性。默认 False。
CULLINAN_STRICT_PRIVATE_INJECTION	环境变量	配置	设为 1/true/yes 可对所有 ApplicationContext 实例全局启用 strict_private_injection。

弃用符号（v0.97 移除）

符号	替代方案
injectable	@service / @component / @controller
inject_constructor	ApplicationContext.refresh()
InjectionRegistry	ApplicationContext / get_application_context()
get_injection_registry()	ApplicationContext / get_application_context()
reset_injection_registry()	显式创建新的 ApplicationContext

详见 框架语义 §5-§8。

重新生成 API 文档（步骤示例）

在后续实现自动化时，可以选择使用静态分析脚本生成 API 索引并更新本页面。典型流程示例：

1. 在 docs/work/ 目录下维护一个用于扫描模块并生成 Markdown 片段的脚本（例如 generate_api_reference.py）。
2. 脚本输出按模块划分的 API 列表（类、函数、签名、简要说明），写入 docs/work/api_modules.md 或直接更新本页面。
3. 在 CI 或本地构建流程中定期运行该脚本，保证 API 参考与源码保持同步。

具体实现细节可根据项目约定和工具链选择进行补充。