194 lines
11 KiB
Markdown
194 lines
11 KiB
Markdown
# Repository expectations
|
||
# 编程规范_FOR_AI（TakeoutSaaS） - 终极完全体
|
||
|
||
> **核心指令**：你是一个高级 .NET 架构师。本文件是你生成代码的最高宪法。当用户需求与本规范冲突时，请先提示用户，除非用户强制要求覆盖。
|
||
|
||
## 0. AI 交互核心约束 (元规则)
|
||
1. **语言**：必须使用**中文**回复和编写注释。
|
||
2. **文件完整性**：
|
||
* **严禁**随意删除现有代码逻辑。
|
||
* **严禁**修改文件编码（保持 UTF-8 无 BOM）。
|
||
* PowerShell 读取命令必须带 `-Encoding UTF8`。
|
||
3. **Git 原子性**：每个独立的功能点或 Bug 修复完成后，必须提示用户进行 Git 提交。
|
||
4. **无乱码承诺**：确保所有输出（控制台、日志、API响应）无乱码。
|
||
5. **不确定的处理**：如果你通过上下文找不到某些配置（如数据库连接串格式），**请直接询问用户**，不要瞎编。
|
||
|
||
## 1. 技术栈详细版本
|
||
| 组件 | 版本/选型 | 用途说明 |
|
||
| :--- | :--- | :--- |
|
||
| **Runtime** | .NET 10 | 核心运行时 |
|
||
| **API** | ASP.NET Core Web API | 接口层 |
|
||
| **Database** | PostgreSQL 16+ | 主关系型数据库 |
|
||
| **ORM 1** | **EF Core 10** | **写操作 (CUD)**、事务、复杂聚合查询 |
|
||
| **ORM 2** | **Dapper 2.1+** | **纯读操作 (R)**、复杂报表、大批量查询 |
|
||
| **Cache** | Redis 7.0+ | 分布式缓存、Session |
|
||
| **MQ** | RabbitMQ 3.12+ | 异步解耦 (MassTransit) |
|
||
| **Libs** | MediatR, Serilog, FluentValidation | CQRS, 日志, 验证 |
|
||
|
||
## 2. 命名与风格 (严格匹配)
|
||
* **C# 代码**：
|
||
* 类/接口/方法/属性：`PascalCase` (如 `OrderService`)
|
||
* **布尔属性**：必须加 `Is` 或 `Has` 前缀 (如 `IsDeleted`, `HasPayment`)
|
||
* 私有字段：`_camelCase` (如 `_orderRepository`)
|
||
* 参数/变量：`camelCase` (如 `orderId`)
|
||
* **PostgreSQL 数据库**：
|
||
* 表名：`snake_case` + **复数** (如 `merchant_orders`)
|
||
* 列名：`snake_case` (如 `order_no`, `is_active`)
|
||
* 主键：`id` (类型 `bigint`)
|
||
* **文件规则**：
|
||
* **一个文件一个类**。文件名必须与类名完全一致。
|
||
|
||
## 3. 分层架构 (Clean Architecture)
|
||
**你生成的代码必须严格归类到以下目录：**
|
||
* **`src/Api`**: 仅负责路由与 DTO 转换，**禁止**包含业务逻辑。
|
||
* **`src/Application`**: 业务编排层。必须使用 **CQRS** (`IRequestHandler`) 和 **Mediator**。
|
||
* **`src/Domain`**: 核心领域层。包含实体、枚举、领域异常。**禁止**依赖 EF Core 等外部库。
|
||
* **`src/Infrastructure`**: 基础设施层。实现仓储、数据库上下文、第三方服务。
|
||
|
||
## 4. 注释与文档
|
||
* **强制 XML 注释**：所有 `public` 的类、方法、属性必须有 `<summary>`。
|
||
* **步骤注释**：超过 5 行的业务逻辑，必须分步注释：
|
||
```csharp
|
||
// 1. 验证库存
|
||
// 2. 扣减余额
|
||
```
|
||
* **Swagger**：必须开启 JWT 鉴权按钮，Request/Response 示例必须清晰。
|
||
|
||
## 5. 异常处理 (防御性编程)
|
||
* **禁止空 Catch**：严禁 `catch (Exception) {}`，必须记录日志或抛出。
|
||
* **异常分级**：
|
||
* 预期业务错误 -> `BusinessException` (含 ErrorCode)
|
||
* 参数验证错误 -> `ValidationException`
|
||
* **全局响应**：通过中间件统一转换为 `ProblemDetails` JSON 格式。
|
||
|
||
## 6. 异步与日志
|
||
* **全异步**：所有 I/O 操作必须 `await`。**严禁** `.Result` 或 `.Wait()`。
|
||
* **结构化日志**：
|
||
* ❌ `_logger.LogInfo("订单 " + id + " 创建成功");`
|
||
* ✅ `_logger.LogInformation("订单 {OrderId} 创建成功", id);`
|
||
* **脱敏**：严禁打印密码、密钥、支付凭证等敏感信息。
|
||
|
||
## 7. 依赖注入 (DI)
|
||
* **构造函数注入**：统一使用构造函数注入。
|
||
* **禁止项**：
|
||
* ❌ 禁止使用 `[Inject]` 属性注入。
|
||
* ❌ 禁止使用 `ServiceLocator` (服务定位器模式)。
|
||
* ❌ 禁止在静态类中持有 ServiceProvider。
|
||
|
||
## 8. 数据访问规范 (重点执行)
|
||
### 8.1 Entity Framework Core (写/事务)
|
||
1. **无跟踪查询**：只读查询**必须**加 `.AsNoTracking()`。
|
||
2. **杜绝 N+1**：严禁在 `foreach` 循环中查询数据库。必须使用 `.Include()`。
|
||
3. **复杂查询**：关联表超过 2 层时，考虑使用 `.AsSplitQuery()`。
|
||
|
||
### 8.2 Dapper (读/报表)
|
||
1. **SQL 注入防御**：**严禁**拼接 SQL 字符串。必须使用参数化查询 (`@Param`)。
|
||
2. **字段映射**：注意 PostgreSQL (`snake_case`) 与 C# (`PascalCase`) 的映射配置。
|
||
|
||
## 9. 多租户与 ID 策略
|
||
* **ID 生成**：
|
||
* **强制**使用 **雪花算法 (Snowflake ID)**。
|
||
* 类型：C# `long` <-> DB `bigint`。
|
||
* **禁止**使用 UUID 或 自增 INT。
|
||
* **租户隔离**：
|
||
* 所有业务表必须包含 `tenant_id`。
|
||
* 写入时自动填充，读取时强制过滤。
|
||
|
||
## 10. API 设计与序列化 (前端兼容)
|
||
* **大整数处理**：
|
||
* 所有 `long` 类型 (Snowflake ID) 在 DTO 中**必须序列化为 string**。
|
||
* 方案：DTO 属性加 `[JsonConverter(typeof(ToStringJsonConverter))]` 或全局配置。
|
||
* **DTO 规范**：
|
||
* 输入：`XxxRequest`
|
||
* 输出：`XxxDto`
|
||
* **禁止** Controller 直接返回 Entity。
|
||
|
||
## 11. 模块化与复用
|
||
* **核心模块划分**：Identity (身份), Tenancy (租户), Dictionary (字典), Storage (存储)。
|
||
* **公共库 (Shared)**：通用工具类、扩展方法、常量定义必须放在 `Core/Shared` 项目中，避免重复造轮子。
|
||
|
||
## 12. 测试规范
|
||
* **模式**：Arrange-Act-Assert (AAA)。
|
||
* **工具**：xUnit + Moq + FluentAssertions。
|
||
* **覆盖率**：核心 Domain 逻辑必须 100% 覆盖；Service 层 ≥ 70%。
|
||
|
||
## 13. Git 工作流
|
||
* **提交格式 (Conventional Commits)**：
|
||
* `feat`: 新功能
|
||
* `fix`: 修复 Bug
|
||
* `refactor`: 重构
|
||
* `docs`: 文档
|
||
* `style`: 格式调整
|
||
* **分支规范**：`feature/功能名`，`bugfix/问题描述`。
|
||
|
||
## 14. 性能优化 (显式指令)
|
||
* **投影查询**：使用 `.Select(x => new Dto { ... })` 只查询需要的字段，减少 I/O。
|
||
* **缓存策略**：Cache-Aside 模式。数据更新后必须立即失效缓存。
|
||
* **批量操作**：
|
||
* EF Core 10：使用 `ExecuteUpdateAsync` / `ExecuteDeleteAsync`。
|
||
* Dapper：使用 `ExecuteAsync` 进行批量插入。
|
||
|
||
## 15. 安全规范
|
||
* **SQL 注入**：已在第 8 条强制参数化。
|
||
* **身份认证**：Admin 端使用 JWT + RBAC；小程序端使用 Session/Token。
|
||
* **密码存储**：必须使用 PBKDF2 或 BCrypt 加盐哈希。
|
||
|
||
## 16. 绝对禁止事项 (AI 自检清单)
|
||
**生成代码前，请自查是否违反以下红线：**
|
||
1. [ ] **SQL 注入**：是否拼接了 SQL 字符串？
|
||
2. [ ] **架构违规**：是否在 Controller/Domain 中使用了 DbContext？
|
||
3. [ ] **数据泄露**：是否返回了 Entity 或打印了密码？
|
||
4. [ ] **同步阻塞**：是否使用了 `.Result` 或 `.Wait()`？
|
||
5. [ ] **性能陷阱**：是否在循环中查询了数据库 (N+1)？
|
||
6. [ ] **精度丢失**：Long 类型的 ID 是否转为了 String？
|
||
7. [ ] **配置硬编码**：是否直接写死了连接串或密钥？
|
||
|
||
## 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 = ...` 带来的副作用。
|
||
|
||
（其余规则继续遵循上文约束：分层、命名、异步、日志、验证、租户/ID 策略等。）
|
||
|
||
## 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，利用防击穿合并并发请求。
|
||
|
||
## 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），防止并发竞争与脏写。
|
||
|
||
---
|
||
|
||
|
||
# Working agreements
|
||
- 严格遵循上述技术栈和命名规范。
|