ADNC Repository 层开发指引

ADNC Repository 层开发指引

GitHub 仓库地址

Repository 层（Repository 工程，或 DDD 场景下的 Domain + Infrastructure）负责数据持久化与查询能力的封装，包括实体建模、映射配置、数据库上下文、仓储接口实现、读写分离/软删除/并发控制等基础能力。Repository 层应专注于“数据访问”，不承载业务编排与事务边界（事务边界建议由服务层控制）。

---

1. 设计原则

• 聚焦数据访问：Repository 只负责持久化与查询，不处理业务规则与流程编排。
• 面向抽象：上层依赖仓储接口而非具体实现，便于测试与替换数据源。
• 查询可组合：优先提供可组合的查询能力（条件、排序、分页），避免为每个查询场景堆叠方法。
• 约束一致：命名、软删除、并发控制、审计字段等横切规则在基础设施层统一实现。

2. 目录结构（示例）

Repository/
├── Entities/                 # 实体
│   └── Config/               # EF Core 映射配置(Fluent API)
├── Migrations/               # 迁移(如单独工程则在 Migrations 工程中)
└── EntityInfo.cs             # 实体注册/扫描(如框架需要)

3. 实体建模规范

• 实体职责：实体只描述数据结构与领域状态，不直接承担应用层编排逻辑。
• 基类选择：根据审计字段、软删除、并发控制等需求选择合适的实体基类/接口（如审计基类、ISoftDelete、IConcurrency）。
• 字段约束：长度、必填、索引等约束以 Fluent API 为主，集中在实体配置类中统一管理。

4. 映射配置（Fluent API）

• 统一放置：建议在 Entities/Config 中为每个实体提供独立的配置类（如 StudentConfig）。
• 显式约束：对长度、精度、默认值、索引、关系（1:1/1:N/N:N）进行显式配置，避免依赖隐式约定。
• 通用规则下沉：如表名/列名规范、软删除过滤器、并发列等，建议在基类配置或 DbContext 中统一处理。

5. 迁移

• 迁移策略：统一迁移命名规范与执行方式（开发/测试/生产），避免多人协作下迁移冲突。
• 环境隔离：不同环境连接字符串与迁移执行策略需明确，避免误将迁移应用到错误环境。

6. 仓储接口与实现建议

• 接口划分：基础仓储接口提供常用 CRUD 与查询能力；特殊查询可通过扩展方法、Specification、或 Dapper/原生 SQL 能力补充。
• 读写分离：如启用读写分离，上层需明确本次查询是否要求走写库（强一致读取），避免隐式行为导致数据不一致。
• 事务边界：仓储方法不主动开启业务事务；多个写操作的事务边界由服务层（Application）统一控制（如 IUnitOfWork 或事务拦截器）。

7. 性能与一致性

• 分页：对分页查询使用稳定排序字段，避免翻页抖动。
• N+1：对导航属性加载采用显式 Include/投影，避免隐式懒加载带来的性能问题。
• 并发控制：对关键写入采用并发标记（行版本/并发字段），并对冲突给出可理解的错误返回。
• 软删除：启用软删除的实体应统一使用全局过滤器，并提供必要的“包含已删除”查询通道（仅限管理场景）。

8. 参考实现

• 实体/映射/迁移示例：参见 docs/wiki/feature-dev-guide-zh.md。
• EF Core 仓储与工作单元：参见 docs/wiki/efcore-pemelo-curd-zh.md 与 docs/wiki/efcore-pemolo-unitofwork-zh.md。
• 原生 SQL 能力：参见 docs/wiki/efcore-pemelo-sql-zh.md。