docs: refine tenant repository comments
This commit is contained in:
112
AGENTS.md
112
AGENTS.md
@@ -47,11 +47,21 @@
|
||||
|
||||
## 4. 注释与文档
|
||||
* **强制 XML 注释**：所有 `public` 的类、方法、属性必须有 `<summary>`。
|
||||
* **步骤注释**：超过 5 行的业务逻辑，必须分步注释：
|
||||
```csharp
|
||||
// 1. 验证库存
|
||||
// 2. 扣减余额
|
||||
```
|
||||
* **分段逻辑注释 (强制)**：
|
||||
* **空行必注**：代码中每当出现空行分隔逻辑块时，**必须**在空行后的第一行添加 `//` 注释，简要说明紧接着这段代码的意图或作用。
|
||||
* **步骤化**：对于稍微复杂的业务逻辑，必须结合序号（1., 2., ...）进行标记。
|
||||
* **示例**：
|
||||
```csharp
|
||||
// 1. 验证用户是否存在
|
||||
var user = await _repo.GetAsync(id);
|
||||
if (user == null) return NotFound();
|
||||
|
||||
// 2. (空行后) 扣减余额逻辑
|
||||
user.Balance -= amount;
|
||||
|
||||
// 3. (空行后) 保存更改
|
||||
await _unitOfWork.SaveChangesAsync();
|
||||
```
|
||||
* **Swagger**：必须开启 JWT 鉴权按钮，Request/Response 示例必须清晰。
|
||||
|
||||
## 5. 异常处理 (防御性编程)
|
||||
@@ -142,50 +152,64 @@
|
||||
5. [ ] **性能陷阱**：是否在循环中查询了数据库 (N+1)？
|
||||
6. [ ] **精度丢失**：Long 类型的 ID 是否转为了 String？
|
||||
7. [ ] **配置硬编码**：是否直接写死了连接串或密钥？
|
||||
8. [ ] **文档注释**：是否给所有 `public` 类/方法/属性添加了 `<summary>`？
|
||||
9. [ ] **逻辑注释**：是否在每个空行分隔的逻辑块上方添加了说明注释？
|
||||
|
||||
## 17. .NET 10 / C# 14 现代语法最佳实践（增量）
|
||||
> 2025 年推荐的 20 条语法规范，新增特性优先，保持极简。
|
||||
1. **field 关键字**：属性内直接使用 `field` 处理后备字段，`set => field = value.Trim();`。
|
||||
2. **空值条件赋值 `?.=`**：仅对象非空时赋值，减少 `if`。
|
||||
3. **未绑定泛型 nameof**：`nameof(List<>)` 获取泛型类型名，无需占位类型参数。
|
||||
4. **Lambda 参数修饰符**：在 Lambda 中可用 `ref/out/in` 与默认参数，例如 `(ref int x, int bonus = 10) => x += bonus;`。
|
||||
5. **主构造函数 (Primary Constructor)**：服务/数据类优先 `class Foo(IDep dep, ILogger<Foo> logger) { }`。
|
||||
6. **record/required/init**：DTO 默认用 record；关键属性用 `required`；不可变属性用 `init`。
|
||||
7. **集合表达式与展开**：使用 `[]` 创建集合，`[..other]` 拼接，`str[1..^1]` 进行切片。
|
||||
8. **模式匹配**：列表模式 `[1, 2, .. var rest]`、属性模式 `{ IsActive: true }`、switch 表达式简化分支。
|
||||
9. **文件范围命名空间/全局 using**：减少缩进与重复引用；复杂泛型用别名。
|
||||
10. **顶级语句**：Program.cs 保持顶级语句风格。
|
||||
11. **原始/UTF-8 字面量**：多行文本用 `"""`，性能场景用 `"text"u8`。
|
||||
12. **不可变命令优先**：命令/DTO 优先用 record 和 `with` 非破坏性拷贝，例如 `command = command with { MerchantId = merchantId };`，避免直接 `command.Property = ...` 带来的副作用。
|
||||
## 17. 现代语法范式 (.NET 10 / C# 14)
|
||||
> **原则**：拥抱新特性以减少样板代码，但严禁牺牲可读性。
|
||||
|
||||
（其余规则继续遵循上文约束：分层、命名、异步、日志、验证、租户/ID 策略等。）
|
||||
1. **主构造函数 (Primary Constructor)**：
|
||||
* **强制**：依赖注入场景必须使用 `class Service(IDep dep) { }`。
|
||||
* **禁止**：在主构造函数类中显式定义 `private readonly` 字段来承接参数（直接使用参数即可）。
|
||||
2. **对象初始化与不可变性**：
|
||||
* **DTO/Command**：必须使用 `record` 类型。
|
||||
* **属性定义**：默认使用 `init`；必填项加 `required`；逻辑变更使用 `with` 表达式。
|
||||
3. **集合表达式**：
|
||||
* **统一**：使用 `[]` 初始化集合。
|
||||
* **拼接**：使用 `[..array1, ..array2]` 替代 `Concat`。
|
||||
4. **模式匹配 (Pattern Matching)**：
|
||||
* **替代**：严禁复杂的 `if-else if` 链，强制使用 `switch` 表达式。
|
||||
* **判空**：使用 `is not null` 替代 `!= null`。
|
||||
5. **极简语法糖**：
|
||||
* **Field 关键字**：属性后备字段必须使用 `field` 关键字（如 `set => field = value.Trim();`）。
|
||||
* **空值赋值**：使用 `?.=` 简化判空赋值逻辑。
|
||||
* **字符串**：多行文本强制用 `"""` (Raw String Literal)。
|
||||
|
||||
## 18. .NET 10 极致性能优化最佳实践（增量）
|
||||
> 侧重零分配、并发与底层优化，遵循 2025 推荐方案。
|
||||
1. **Span/ReadOnlySpan 优先**：API 参数尽量用 `ReadOnlySpan<char>` 处理字符串/切片，避免 Substring/复制。
|
||||
2. **栈分配与数组池**：小缓冲用 `stackalloc`，大缓冲统一用 `ArrayPool<T>.Shared`，禁止直接 `new` 大数组。
|
||||
3. **UTF-8 字面量**：常量字节使用 `"text"u8`，避免运行时编码。
|
||||
4. **避免装箱**：热点路径规避隐式装箱，必要时用 `ref struct` 约束栈分配。
|
||||
5. **Frozen 集合**：只读查找表用 `FrozenDictionary/FrozenSet`，初始化后不再修改。
|
||||
6. **SearchValues SIMD 查找**：Span 内多字符搜索用 `SearchValues.Create(...)` + `ContainsAny`。
|
||||
7. **预设集合容量**：`List/Dictionary` 预知规模必须指定 `Capacity`。
|
||||
8. **ValueTask 热点返回**：可能同步完成的异步返回 `ValueTask<T>`，减少 Task 分配。
|
||||
9. **Parallel.ForEachAsync 控并发**：I/O 并发用 Parallel.ForEachAsync 控制并行度，替代粗暴 Task.WhenAll。
|
||||
10. **避免 Task.Run**：在 ASP.NET Core 请求中不使用 Task.Run 做后台工作，改用 IHostedService 或 Channel 模式。
|
||||
11. **Channel<T> 代替锁**：多线程数据传递优先使用 Channels，实现无锁生产者-消费者。
|
||||
12. **NativeAOT/PGO/向量化**：微服务/工具开启 NativeAOT；保留动态 PGO；计算密集场景考虑 System.Runtime.Intrinsics。
|
||||
13. **System.Text.Json + 源生成器**：全面替换 Newtonsoft.Json；使用 `[JsonSerializable]` + 生成的 `JsonSerializerContext`，兼容 NativeAOT，零反射。
|
||||
14. **Pipelines 处理流**：TCP/文件流解析使用 `PipeReader/PipeWriter`，获得零拷贝与缓冲管理。
|
||||
15. **HybridCache**：内存+分布式缓存统一用 HybridCache，利用防击穿合并并发请求。
|
||||
## 18. 极致性能规约 (High Performance)
|
||||
> **原则**：默认编写“零分配 (Zero-Allocation)”代码，热点路径拒绝 GC 压力。
|
||||
|
||||
## 19. 架构优化（增量）
|
||||
> 架构优化方案
|
||||
1. **Chiseled 容器优先**：生产镜像基于 `mcr.microsoft.com/dotnet/runtime-deps:10.0-jammy-chiseled`，无 Shell、非 root，缩小攻击面，符合零信任要求。
|
||||
2. **默认集成 OpenTelemetry**：架构内置 OTel，统一通过 OTLP 导出 Metrics/Traces/Logs，避免依赖专有 APM 探针。
|
||||
3. **内部同步调用首选 gRPC**：微服务间禁止 JSON over HTTP，同步调用统一使用 gRPC，配合 Protobuf 源生成器获取强类型契约与更小载荷。
|
||||
4. **Outbox 模式强制**：处理领域事件时，事件记录必须与业务数据同事务写入 Outbox 表；后台 Worker 轮询 Outbox 再推送 MQ（RabbitMQ/Kafka），禁止事务提交后直接发消息以避免不一致。
|
||||
5. **共享资源必加分布式锁**：涉及库存扣减、定时任务抢占等共享资源时，必须引入分布式锁（如 Redis RedLock），防止并发竞争与脏写。
|
||||
1. **内存管理**：
|
||||
* **字符串处理**：API 参数解析层**强制**使用 `ReadOnlySpan<char>`，严禁使用 `Substring`。
|
||||
* **数组分配**：小块内存 (<1KB) 使用 `stackalloc`；大块内存 (>1KB) 必须使用 `ArrayPool<T>.Shared`。
|
||||
2. **并发模型**：
|
||||
* **无锁编程**：进程内生产者-消费者模型**必须**使用 `System.Threading.Channels`，严禁使用 `lock` 或 `BlockingCollection`。
|
||||
* **并行控制**：I/O 密集型并发必须使用 `Parallel.ForEachAsync` 并配置 `MaxDegreeOfParallelism`。
|
||||
* **异步返回**：热点路径下，若可能同步完成，返回类型必须为 `ValueTask<T>`。
|
||||
3. **序列化与查找**：
|
||||
* **JSON**：**全线废弃** Newtonsoft.Json。必须使用 `System.Text.Json` 配合源生成器 (`[JsonSerializable]`) 以支持 NativeAOT。
|
||||
* **静态集合**：只读字典/集合**必须**使用 `FrozenDictionary` / `FrozenSet`。
|
||||
* **SIMD 搜索**：多字符匹配场景使用 `SearchValues` 替代 `IndexOfAny`。
|
||||
4. **缓存架构**：
|
||||
* **统一入口**：必须使用 `HybridCache` (或类似多级缓存抽象)，禁止直接操作 `IDistributedCache` 以避免缓存击穿。
|
||||
|
||||
## 19. 云原生架构规范 (Architecture)
|
||||
> **原则**：默认零信任，默认分布式，默认可观测。
|
||||
|
||||
1. **容器与部署**：
|
||||
* **基底镜像**：生产环境**强制**使用 Chiseled 镜像 (`runtime-deps:10.0-jammy-chiseled`)，无 Shell、无 Root，最大化安全。
|
||||
* **健康检查**：必须包含 Liveness (存活) 和 Readiness (就绪) 探针。
|
||||
2. **服务间通信**：
|
||||
* **同步调用**：内部微服务间**严禁**使用 REST/JSON，**必须**使用 gRPC (Protobuf)。
|
||||
* **契约管理**：Proto 文件必须作为单一事实来源 (Single Source of Truth) 统一管理。
|
||||
3. **数据一致性 (关键)**：
|
||||
* **Outbox 模式**：领域事件发布**严禁**直接调用 MQ。必须在同一数据库事务中写入 `Outbox` 表，由独立 Worker 异步推送。
|
||||
* **幂等性**：所有消费者 (Consumer) 必须实现基于 `MessageId` 的幂等处理逻辑。
|
||||
4. **可观测性 (Observability)**：
|
||||
* **OpenTelemetry**：严禁依赖特定厂商 SDK。必须统一输出 OTLP 标准格式 (Metrics/Logs/Traces)。
|
||||
* **关联ID**：确保 `TraceId` 在 HTTP Headers 和 MQ Metadata 中全程透传。
|
||||
5. **并发控制**：
|
||||
* **分布式锁**：任何涉及跨实例的资源竞争（如库存扣减、定时任务），**必须**使用 Redis RedLock 或同等机制。
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user