80 lines
3.3 KiB
Markdown
80 lines
3.3 KiB
Markdown
# 编程规范_FOR_AI（TakeoutSaaS）
|
||
|
||
说明：本规范为AI编程助手与开发者共同遵循的统一编码规范，结合 0_Document 下文档约定（特别是 06_开发规范.md、02_技术架构.md、12.* 规范）执行。超出本文件内容的详细条目请以文档中心为准。
|
||
|
||
## 1. 技术栈
|
||
- .NET 10 + ASP.NET Core Web API
|
||
- EF Core 10（复杂关系/事务）+ Dapper（统计/批量）+ PostgreSQL 16+
|
||
- Redis、RabbitMQ、Swagger、MediatR、Serilog、FluentValidation、AutoMapper、Hangfire、Polly
|
||
|
||
## 2. 命名与风格
|
||
- 类/方法/属性：PascalCase；接口：I前缀；私有字段：_camelCase；变量：camelCase；常量：PascalCase
|
||
- 每文件仅1个公共类型，文件名与类型名一致
|
||
- 命名空间与目录结构一致
|
||
|
||
## 3. 分层与结构
|
||
- 物理结构：Api（AdminApi/MiniApi/UserApi）+ Application + Domain + Infrastructure + Core(Shared.*) + Modules + Gateway
|
||
- 不允许在Controller/Service中直接操作DbContext，必须通过仓储/应用服务
|
||
- 返回DTO，禁止直接返回实体
|
||
|
||
## 4. 注释与文档
|
||
- 所有公共API、接口、复杂逻辑必须有XML注释
|
||
- 控制器、服务方法提供简要说明与异常声明
|
||
|
||
## 5. 异常与错误码
|
||
- 使用 BusinessException（含ErrorCode）/ ValidationException；禁止吞异常
|
||
- 全局异常中间件输出 ProblemDetails（扩展code与errors）
|
||
- 错误码：400/401/403/404/409/422/500 + 业务10001+
|
||
|
||
## 6. 异步与日志
|
||
- 全面使用 async/await，禁止 .Result/.Wait()
|
||
- 使用 Serilog 记录结构化日志，避免记录敏感数据
|
||
|
||
## 7. 依赖注入
|
||
- 统一使用构造函数注入，禁止服务定位器
|
||
- 业务逻辑在应用层，仓储在基础设施层
|
||
|
||
## 8. 数据访问
|
||
- EF Core 10 负责关系/事务/迁移；Dapper 负责统计和大批量
|
||
- 使用工作单元与仓储模式；避免N+1；只读查询使用AsNoTracking
|
||
- 参数化查询，禁止字符串拼接SQL
|
||
|
||
## 9. 多租户
|
||
- 通过 Header:X-Tenant-Id 或 Token Claim: tenant_id 解析租户
|
||
- EF Core 全局过滤（tenant_id）；写入数据时自动填充租户
|
||
|
||
## 10. 安全
|
||
- HTTPS、Security Headers、CORS按端配置
|
||
- 授权：AdminApi 使用JWT+RBAC；MiniApi 小程序登录态+JWT
|
||
- 严禁日志打印密码/支付信息等敏感数据
|
||
|
||
## 11. API 设计
|
||
- RESTful，统一 /api/{area}/v{version}
|
||
- 统一返回：ApiResponse<T>；分页返回使用 PagedResult<T>
|
||
- Swagger 按版本与端分组，开启鉴权按钮
|
||
|
||
## 12. 模块化
|
||
- 独立模块抽象：Identity、Authorization、Tenancy、Dictionary、Storage、Sms、Messaging、Scheduler、Delivery
|
||
- 公共横切能力抽到 Shared.* 复用
|
||
|
||
## 13. 测试
|
||
- xUnit + Moq + FluentAssertions；命名：Method_Scenario_Expected
|
||
- 核心业务覆盖率≥80%
|
||
|
||
## 14. Git 提交
|
||
- 使用 Conventional Commits：feat/fix/docs/style/refactor/perf/test/chore
|
||
|
||
## 15. 性能
|
||
- 投影查询、编译查询、批量操作（ExecuteUpdate/ExecuteDelete）
|
||
- 缓存优先：Cache-Aside；更新后清缓存
|
||
|
||
## 16. 禁止事项
|
||
- 直接使用DbContext（绕过仓储/工作单元）
|
||
- 硬编码配置（使用IOptions）
|
||
- 返回实体类
|
||
- SQL拼接注入风险
|
||
- 吞异常或静默失败
|
||
- 同步阻塞异步
|
||
|
||
以上规范将随着文档中心的演进不断完善；AI编程助手生成的代码必须符合本规范，并默认使用这些约束。
|