436 lines
15 KiB
Markdown
436 lines
15 KiB
Markdown
# XXX 项目复刻开发说明
|
||
|
||
> 目的：基于当前项目快速开发一个“风格完全一致”的新项目。
|
||
> 使用方式：先完整阅读本文，再按“复刻步骤清单”执行。
|
||
> 本文最高优先级：出入参模型、分页列表、出入参约定、路由约定、服务约定。后续新增功能如果与历史存量代码存在轻微写法差异，新增代码优先遵循本文，不再继续扩散不一致风格。
|
||
|
||
## 1. 项目定位与技术基线
|
||
|
||
- 运行时：`.NET 8`（`global.json` 固定为 `8.0.303`）。
|
||
- 架构风格：`Fake` 模块化 + 分层架构（API / Application / Repositories / Domain）。
|
||
- 容器与日志：`Autofac` + `Serilog`。
|
||
- 配置中心：`Consul`（启动时加载公共与业务配置）。
|
||
- ORM：`SqlSugar`（MySQL）。
|
||
- 缓存：`FreeRedis`。
|
||
- 消息：`RabbitMQ`（事件总线）。
|
||
- 序列化：`Newtonsoft.Json`（统一驼峰、DateTime/Long 转换）。
|
||
|
||
## 2. 解决方案结构（必须保持）
|
||
|
||
`XXX.sln` 当前核心项目：
|
||
|
||
- `src/XXX.Api`：Web 入口、鉴权、Swagger、CORS、过滤器、路由暴露。
|
||
- `src/XXX.Application`：业务编排层（Service、HostService）。
|
||
- `src/XXX.Domain`：共享枚举、常量、转换器、通用 DTO、实体、仓储接口
|
||
- `src/XXX.Repositories`：仓储实现、数据库访问、基础设施
|
||
|
||
建议新项目保持同样的目录和分层职责，不要把 Repository 逻辑放到 Application，也不要把业务规则放到 API 层。
|
||
|
||
## 3. 复刻时必须优先统一的五类约定
|
||
|
||
这一节是本文最重要的部分。后续开发是否能“照着文档就写出风格一致的代码”，主要取决于这五类约定是否被严格执行。
|
||
|
||
### 3.1 出入参模型分层约定
|
||
|
||
当前项目真实风格是“所有 DTO 都放 Domain”，而是按“写模型”和“读模型”分层：
|
||
|
||
- 出参入参放 `Application/Dtos/<领域>/`。
|
||
- 跨模块复用、通用基类、公共查询基类放 `Domainon/Dtos/`。
|
||
- Entity 只用于持久化，不直接作为 API 出参返回给前端。
|
||
|
||
命名建议按当前项目风格收敛：
|
||
|
||
- 写操作入参：`CreateXxxInput`、`UpdateXxxInput`、`SaveXxxInput`、`CheckXxxInput`、`DeleteXxxInput`。
|
||
- 分页查询入参：`XxxPaginatedInput` 或 `XxxPaginatedInput`。
|
||
- 详情出参：`XxxOutput`。
|
||
- 分页列表出参：`XxxPaginatedOutput` 或 `XxxListOutput`。
|
||
- 树形出参：`XxxTreeListOutput`。
|
||
- 下拉出参：`XxxDropdownOutput` / `XxxDropDownItem`。
|
||
|
||
落地规则：
|
||
|
||
- 同一个领域内，命名风格必须保持一致，不要同时出现 `AppListOutput`、`AppListItemDto` 两种并存写法。
|
||
- “保存类”接口的入参一律使用明确 Input 模型，不要直接收多个散参数。
|
||
- 列表、树、级联、下拉等只读接口，允许直接返回 Dto，这是当前项目主流风格。
|
||
- 集合类型属性统一显式初始化，例如 `= new();`，避免空引用分支扩散。
|
||
|
||
### 3.2 分页列表约定
|
||
|
||
分页是后续最容易写散的部分，必须统一。
|
||
|
||
统一契约：
|
||
|
||
- 分页入参必须继承 `PagedQueryInput`。
|
||
- `PagedQueryInput` 统一只提供 `PageIndex`、`PageSize` 两个基础字段。
|
||
- 分页返回值统一使用 `PagedResult<T>`。
|
||
- 分页查询最终统一通过 `ToPagedListAsync(input.PageIndex, input.PageSize)` 收口。
|
||
- 分页列表默认按 `UpdateTime` 或明确业务时间字段倒序，不允许无序分页。
|
||
|
||
当前项目基线可直接复用：
|
||
|
||
```csharp
|
||
public class PagedQueryInput
|
||
{
|
||
public int PageIndex { get; set; }
|
||
|
||
public int PageSize { get; set; }
|
||
}
|
||
```
|
||
|
||
```csharp
|
||
public static async Task<PagedResult<TEntity>> ToPagedListAsync<TEntity>(
|
||
this ISugarQueryable<TEntity> query,
|
||
int pageIndex,
|
||
int pageSize) where TEntity : class
|
||
{
|
||
RefAsync<int> totalCount = 0;
|
||
var items = await query.ToPageListAsync(pageIndex, pageSize, totalCount);
|
||
|
||
return new PagedResult<TEntity>(totalCount, items);
|
||
}
|
||
```
|
||
|
||
分页接口统一要求：
|
||
|
||
- 简单下拉、树形、级联不要伪装成分页，直接返回 `List<T>`。
|
||
- 复杂筛选分页优先 `POST` + 一个完整 Input 模型，不要拆成很多 Query 参数。
|
||
- 除非确实是动态列场景，否则分页出参必须使用强类型模型，不要默认返回 `Dictionary<string, object?>`。
|
||
- 动态列分页属于例外能力，只能在“字段配置驱动展示列”的场景使用。
|
||
|
||
### 3.3 出入参约定
|
||
|
||
新增接口时，优先按以下规则写：
|
||
|
||
- `GET`：仅用于详情、下拉、字典、简单查询，参数来自 Query。
|
||
- `POST`：用于分页查询、复杂筛选、保存、校验、导入导出等。
|
||
- `PUT`：用于明确语义的更新动作，项目里已有使用，但不是主流；是否使用要在同一领域内保持一致。
|
||
- `DELETE`：仅在该领域已经采用 REST 风格时继续沿用；否则统一使用 `POST("Xxx/Delete")` 或 `POST("Xxx/DeleteByIds")`。
|
||
|
||
参数组织约定：
|
||
|
||
- 简单标量参数用 `[Required]` 标记必填。
|
||
- 可选筛选字段统一使用可空类型或 `string?`。
|
||
- 保存型接口尽量只接收一个 Input 对象。
|
||
- 批量操作参数命名统一为 `ids`、`items`、`list` 之一，不要同义混写。
|
||
- 枚举字段优先直接使用枚举类型，不要在 Application 层传播魔法数字。
|
||
|
||
返回值约定：
|
||
|
||
- 详情：返回单个 `XxxOutput` / `XxxValueObject`。
|
||
- 列表：返回 `List<T>`。
|
||
- 分页：返回 `PagedResult<T>`。
|
||
- 保存新增：优先返回主键 `int` 或 `long`。
|
||
- 修改、删除、校验：优先返回 `bool`。
|
||
- 有业务语义的失败统一抛 `BusinessException`。
|
||
|
||
### 3.4 路由约定
|
||
|
||
路由必须显式声明，不能依赖默认约定路由。
|
||
|
||
统一规则：
|
||
|
||
- 路由模式统一为：`<领域>/<动作>`。
|
||
- 路由使用 PascalCase，与当前项目风格保持一致。
|
||
- 方法名保留 `Async` 后缀，但路由名不要再继续扩散 `Async` 后缀。
|
||
- 新增代码优先在方法上直接写完整业务路由，例如 `[HttpPost("ServiceProvider/PaginatedList")]`。
|
||
- 如果某个 Service 已使用类级别 `[Route("App")]`，则该类内所有 Action 都保持同一套路，不要一半类路由、一半全路径。
|
||
|
||
推荐动作命名：
|
||
|
||
- 分页：`<Domain>/PaginatedList`
|
||
- 树形：`<Domain>/GetTreeList`
|
||
- 下拉：`<Domain>/GetDropdownList`
|
||
- 详情：`<Domain>/GetById` 或 `<Domain>/GetXxxById`
|
||
- 新增：`<Domain>/Create` 或 `<Domain>/Add`
|
||
- 修改：`<Domain>/Update`
|
||
- 删除：`<Domain>/Delete` / `<Domain>/DeleteByIds`
|
||
- 保存型合并动作：`<Domain>/Save`
|
||
- 批量动作：`<Domain>/BatchXxx`
|
||
|
||
|
||
### 3.5 服务约定
|
||
|
||
服务层风格统一，才能保证后续代码一眼能看懂。
|
||
|
||
`ApplicationService` 职责：
|
||
|
||
- 对外暴露 API。
|
||
- 做参数校验、业务校验、权限入口控制。
|
||
- 组织事务边界。
|
||
- 调用 Repository、其他 Service、缓存、事件、外部 HTTP。
|
||
- 做输入输出对象转换。
|
||
|
||
`Repository` 职责：
|
||
|
||
- 封装数据库读写。
|
||
- 封装分页、投影、子查询、多表查询。
|
||
- 对外提供稳定查询方法，不把 SqlSugar 细节扩散到上层。
|
||
|
||
禁止事项：
|
||
|
||
- 不在 API 层写业务逻辑。
|
||
- 不把 Entity 直接返回前端。
|
||
- 不在 Service 中大段拼接复杂多表查询。
|
||
- 不把事务边界拆散到多个 Controller / Action 外部调用中。
|
||
|
||
推荐服务拆分方式：
|
||
|
||
- 一个领域一个主服务，例如 `InterfaceService`、`ServiceProviderService`。
|
||
- 独立子职责可拆成并列服务，例如 `ServiceProviderAuthService`、`ServiceProviderAccountService`。
|
||
- HostService、Forward 流程、过滤器、缓存辅助逻辑不要混进普通 CRUD 服务。
|
||
|
||
依赖注入约定：
|
||
|
||
- 当前项目同时存在构造函数注入和 `LazyServiceProvider.GetRequiredService<T>()` 两种风格。
|
||
- 新增类时可以二选一，但同一个类内不要混用。
|
||
- 如果是复刻某个现有服务，优先延续该服务当前风格，不要做无必要切换。
|
||
|
||
## 4. 全局编码约定（从现有代码提炼）
|
||
|
||
### 4.1 命名与组织
|
||
|
||
- 项目命名采用：`<产品名>.<层名>`，例如 `XXX.Application`。
|
||
- 实体、仓储接口目录放在 `Domain/<领域>Aggregate`
|
||
- 业务服务放在 `Application/Services/<领域>/`。
|
||
- 仓储实现放在 `Repositories/<领域>/`。
|
||
- 只读投影模型放在 `Domain/Dtos/<领域>/`。
|
||
- 写操作 DTO 放在 `Application/Dtos/<领域>/`。
|
||
|
||
### 4.2 API 风格
|
||
|
||
- 业务服务类继承 `ApplicationService`，直接作为控制器暴露。
|
||
- 默认全局鉴权，匿名访问需要明确放开。
|
||
- 统一使用 Swagger 分组标记 `ApiExplorerSettings(GroupName = "...")`。
|
||
- 错误处理使用 `BusinessException` 体现业务语义。
|
||
|
||
### 4.3 数据访问风格
|
||
|
||
- 仓储实现继承 `BasicRepository<TEntity>`。
|
||
- 查询统一基于 `AsQueryable()` + `WhereIF` + `Select<DTO>()`。
|
||
- 分页统一返回 `PagedResult<T>`。
|
||
- 多表/子查询场景通过 `LeftJoin`、`SqlFunc.Subqueryable<>()` 等方式收口在 Repository 内部。
|
||
|
||
### 4.4 事务与一致性
|
||
|
||
- 涉及多表写入（主表 + 参数 + 关联表）必须显式事务。
|
||
- 统一写法：
|
||
|
||
```csharp
|
||
using var ts = TransacationHelper.GetReadCommitted();
|
||
|
||
// 1. 校验
|
||
// 2. 持久化
|
||
// 3. 清缓存 / 发事件
|
||
|
||
ts.Complete();
|
||
```
|
||
|
||
- 事务粒度按“一个完整业务动作”控制，不要半截提交。
|
||
|
||
## 5. 启动链路与模块装配（复刻重点）
|
||
|
||
### 5.1 API 启动（`XXX.Api/Program.cs`）
|
||
|
||
必须保留的关键顺序：
|
||
|
||
1. `CreateSlimBuilder(args)`。
|
||
2. `AddConsul("idwms/common")` 与业务配置节点。
|
||
3. `UseAutofac().UseSerilog()`。
|
||
4. `AddApplication<YourApiModule>()`。
|
||
5. `AddServiceDefaults()`。
|
||
6. `Build()` 后 `InitializeApplication()` 再 `Run()`。
|
||
|
||
### 5.2 API 模块（`XXXApiModule`）
|
||
|
||
模块中应保留这些能力：
|
||
|
||
- 全局 Claim 映射（`FakeClaimTypes.UserId`）。
|
||
- `ApplicationServices2Controller<...>()` 自动控制器映射。
|
||
- 全局授权策略（默认全部接口需登录）。
|
||
- JSON 序列化配置（驼峰 + 自定义 converter）。
|
||
- Swagger + 审计。
|
||
- CORS 从 `App:CorsOrigins` 读取。
|
||
- 代理头配置（支持 Nginx 获取真实 IP）。
|
||
- 中间件顺序：异常处理 -> 默认端点 -> PathBase -> Swagger -> CORS -> Routing -> Auth -> ForwardedHeaders -> Controllers。
|
||
|
||
### 5.3 Application 模块
|
||
|
||
必须包含：
|
||
|
||
- AutoMapper Profile 扫描。
|
||
- Options 绑定（如 `InterfaceRelay`）。
|
||
- HostService 注册。
|
||
- Redis 初始化（缺配置直接抛异常）。
|
||
- 预热逻辑（如 `NatashaInitializer.Preheating()`）。
|
||
- 命名 HttpClient（统一超时与 SSL 策略）。
|
||
|
||
### 5.4 Repositories 模块
|
||
|
||
必须包含：
|
||
|
||
- SqlSugar DbContext 注册（连接串来自 `ConnectionStrings:Default`）。
|
||
- `IBasicRepository<>` 泛型仓储注册。
|
||
- 其他基础设施配置（例如 ElasticSearch Options）。
|
||
|
||
## 6. 配置规范（新项目必须对齐）
|
||
|
||
`src/XXX.Api/appsettings.json` 仅保留轻量入口配置，核心配置走 Consul。
|
||
|
||
建议保持同结构：
|
||
|
||
- `UseLocalConfigs`
|
||
- `Consul:Address`
|
||
- `Consul:Token`
|
||
|
||
同时在 Consul 准备以下节点（按本项目习惯）：
|
||
|
||
- 公共节点：`idwms/common`
|
||
- 业务节点：`idwms/<你的业务名>`
|
||
|
||
并确保这些节在配置中心可用：
|
||
|
||
- `App:Urls`
|
||
- `App:CorsOrigins`
|
||
- `ConnectionStrings:Default`
|
||
- `Redis`
|
||
- `ElasticSearch`
|
||
- `Serilog`
|
||
- 业务 Options（如 `InterfaceRelay`）
|
||
|
||
## 7. 业务代码写法模板（建议直接复用）
|
||
|
||
### 7.1 分页列表模板
|
||
|
||
推荐把“分页入参 + 分页出参 + Repository 查询 + Application 暴露”整套一起按下面方式写。
|
||
|
||
```csharp
|
||
public class XxxPaginatedInputObjectValue : PagedQueryInput
|
||
{
|
||
public string? Keyword { get; set; }
|
||
|
||
public int? Status { get; set; }
|
||
}
|
||
|
||
public class XxxPaginatedOutputValueObject
|
||
{
|
||
public int Id { get; set; }
|
||
|
||
public string Name { get; set; }
|
||
|
||
public DateTime UpdateTime { get; set; }
|
||
}
|
||
```
|
||
|
||
```csharp
|
||
public interface IXxxRepository : IBasicRepository<XxxEntity>
|
||
{
|
||
Task<PagedResult<XxxPaginatedOutputValueObject>> GetPaginatedListAsync(
|
||
XxxPaginatedInputObjectValue input);
|
||
}
|
||
|
||
public class XxxRepository : BasicRepository<XxxEntity>, IXxxRepository, IScopedDependency
|
||
{
|
||
public async Task<PagedResult<XxxPaginatedOutputValueObject>> GetPaginatedListAsync(
|
||
XxxPaginatedInputObjectValue input)
|
||
{
|
||
var query = AsQueryable();
|
||
|
||
query.WhereIF(!string.IsNullOrWhiteSpace(input.Keyword), x => x.Name.Contains(input.Keyword!))
|
||
.WhereIF(input.Status != null, x => x.Status == input.Status);
|
||
|
||
return await query
|
||
.Select<XxxPaginatedOutputValueObject>()
|
||
.OrderByDescending(x => x.UpdateTime)
|
||
.ToPagedListAsync(input.PageIndex, input.PageSize);
|
||
}
|
||
}
|
||
```
|
||
|
||
```csharp
|
||
[ApiExplorerSettings(GroupName = "示例分组")]
|
||
public class XxxService : ApplicationService
|
||
{
|
||
private IXxxRepository XxxRepository => LazyServiceProvider.GetRequiredService<IXxxRepository>();
|
||
|
||
[HttpPost("Xxx/PaginatedList")]
|
||
public async Task<PagedResult<XxxPaginatedOutputValueObject>> GetPaginatedListAsync(
|
||
XxxPaginatedInputObjectValue input)
|
||
{
|
||
return await XxxRepository.GetPaginatedListAsync(input);
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.2 保存类模板
|
||
|
||
```csharp
|
||
public class SaveXxxInput
|
||
{
|
||
public OptionType OptionType { get; set; }
|
||
|
||
public int? Id { get; set; }
|
||
|
||
public string Name { get; set; }
|
||
|
||
public List<SaveXxxItemInput> Items { get; set; } = new();
|
||
}
|
||
```
|
||
|
||
```csharp
|
||
[ApiExplorerSettings(GroupName = "示例分组")]
|
||
public class XxxService : ApplicationService
|
||
{
|
||
private IXxxRepository XxxRepository => LazyServiceProvider.GetRequiredService<IXxxRepository>();
|
||
|
||
[HttpPost("Xxx/Save")]
|
||
public async Task<int> SaveAsync(SaveXxxInput input)
|
||
{
|
||
if (input.OptionType == OptionType.删除)
|
||
{
|
||
await XxxRepository.SoftDeleteAsync(x => x.Id == input.Id);
|
||
return input.Id ?? 0;
|
||
}
|
||
|
||
using var ts = TransacationHelper.GetReadCommitted();
|
||
|
||
// 1. 业务校验
|
||
// 2. 主表保存
|
||
// 3. 明细保存
|
||
// 4. 清缓存 / 发事件
|
||
|
||
ts.Complete();
|
||
return input.Id ?? 0;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 7.3 路由模板
|
||
|
||
新增领域时，优先按下面这组动作名铺开，后续别人一看就知道接口在哪：
|
||
|
||
- `Xxx/PaginatedList`
|
||
- `Xxx/GetById`
|
||
- `Xxx/GetDropdownList`
|
||
- `Xxx/Create`
|
||
- `Xxx/Update`
|
||
- `Xxx/DeleteByIds`
|
||
- `Xxx/Save`
|
||
|
||
规则：
|
||
|
||
- 只要用了 `Save`，就让 `Save` 明确承担新增/修改/删除的统一入口，不要同时再出现语义重复的 `Submit`、`Edit`、`DoSave`。
|
||
- 只要用了 `PaginatedList`，同领域内就不要再出现 `GetList`、`GetPageList`、`GetPagedData` 多套命名并存。
|
||
|
||
## 8. 复刻步骤清单（按顺序）
|
||
|
||
1. 复制当前解决方案结构，替换项目名前缀（建议全量替换 `XXX`）。
|
||
2. 保持 `global.json`、`Directory.Build.props`、`common.props` 不变或等价。
|
||
3. 按现有模式创建各层 `Module` 并配置 `[DependsOn]`。
|
||
4. 在 API `Program.cs` 保留 Consul、Serilog、Autofac、Fake 初始化顺序。
|
||
5. 完成 `appsettings.json` 与 Consul 节点准备。
|
||
6. 先建 `ApplicatiDomainon` 公共枚举和分页基类，再建 `Contracts DTO`，再建 `Repositories ValueObjects`，最后写 `Repository` 与 `Application Service`。
|
||
7. 先统一路由命名和分页契约，再批量开发业务接口，避免边写边变风格。
|
||
8. 所有多表写入逻辑补齐事务。
|
||
9. 补齐 AutoMapper Profile。
|
||
10. 通过 AppHost 本地启动联调，再单启 API 验证。
|
||
11. 重点检查：鉴权默认开启、CORS、序列化格式、路径基址、代理头、日志落库/落 ES。 |