框架使用与扩展规范

本页定义“项目是否正确使用 AgileLabs Framework”的正式规则。重点不是列功能点，而是明确哪些做法符合框架指导原则，哪些做法属于偏离或反模式。

适用场景

新项目决定是否按框架默认方式接入。
存量项目审查是否存在半框架化、半手工化实现。
需要在框架之上做项目级扩展或包装。

必须遵守

优先使用框架已有能力承接通用问题，例如宿主启动、统一异常链、统一响应封包、WorkContext、审计字段和时间转换。
项目级扩展必须建立在框架默认约定之上，不绕开既有注册点和生命周期边界。
WebAPI、前端契约、时间语义和命名转换必须与正式规范页保持一致，不得各项目自行定义一套默认协议。
同一系统内不允许一部分模块走框架规范，另一部分模块长期靠手工实现维持同类能力。
任何偏离默认规则的地方都必须在项目文档中明确说明原因、范围和替代规则。

推荐做法

保持宿主入口尽量薄，把注册、序列化、异常处理和后台任务接入放到明确扩展点。
把项目级能力封装到公共注册层，而不是分散写在多个 Program.cs 或 Startup 里。
先对齐框架默认规则，再做有限扩展，避免一开始就重写整个接入链。
数据访问新模块默认走 Dapper / SQL 路线；EF Core 仅作为存量兼容方案保留。
审查存量项目时优先检查是否存在重复实现框架已有功能的代码。

运作机制

框架通过宿主配置、统一过滤器、WorkContext、Json 配置和默认 Dapper 数据访问路径提供运行骨架。
项目可以在框架扩展点上增加自己的注册、异常映射和 resolver，但不应跳过这些骨架直接在控制器、仓储或任务里手工兜底。
大型项目可以像案例中的 woscm 一样再包一层项目标准宿主，但底层规则仍应与框架主约定保持一致。

常见问题

“项目要特殊一点，能不能直接自己写一套异常处理和封包？” 不能作为默认方案。可以扩展项目级处理器，但仍应挂在统一异常链上。
“大型系统是不是一定不能直接用框架默认宿主？” 不是。可以加项目标准层，但默认能力仍应复用，而不是推翻。
“历史项目已经混用了多种写法怎么办？” 先用框架使用检查标出偏差点，再分阶段收敛。

相关检查

示例项目对照

niusys-webapi：薄宿主、统一异常链、统一序列化入口。
gmandarin-backend：多宿主共用框架能力并做项目级扩展。
woscm：在框架之上再包项目标准层，但不打散底层规则。