开发约定与规范

项目配置

• 必须使用<Nullable>enable</Nullable>配置项。

实体模型定义

• 所有实体类默认继承自EntityBase，该类定义了Id、CreatedAt、UpdatedAt,IsDeleted常用属性。

• Id属性默认使用Guid类型，客户端Guid V7生成。

• string类型，要定义最大长度，除非明确不限长度。

• decimal类型，精度和小数位数需要明确。

  • 对于较小范围的decimal类型，建议使用decimal(10, 2)

  • 对于较大范围的decimal类型，建议使用decimal(18, 6)

    [Column(TypeName = "decimal(10,2)")]
    public decimal TotalPrice { get; set; }
    

• 所有枚举值必须添加[Description]特性。

• 时间类型使用DateTimeOffset，而不是DateTime，以确保时间信息是完整的。

• 明确仅为日期的属性，使用DateOnly类型。

• 明确仅为时间的属性，使用TimeOnly类型。

服务与帮助类

帮助类通常用Helper结尾，并且Helper类通常是静态类，与DI无关。

服务类通常用Service结尾，并且Service类通常是实现类，通常需要注入到DI中。

业务Manager

• 通常不要为业务实现(Manager)类定义接口，现实中业务多变且只有一个实现类。除非有严格的业务流程，并且有多个实现类的需求。
• Manager继承ManagerBase类，将会被自动注入到DI中。如果不继承，需要手动注入。

接口请求与返回

整体以RESTful风格为标准。

控制器方法命名简单一致，如添加用户，直接使用AddAsync，而不是AddUserAsync，如:

• 添加/创建: AddAsync
• 修改/更新: UpdateAsync
• 删除: DeleteAsync
• 查询详情: GetDetailAsync
• 筛选查询: FilterAsync

请求方式

• GET，获取数据时使用GET，复杂的筛选和条件查询，可改用POST方式传递参数。
• POST，添加数据时使用POST。主体参数使用JSON格式。
• PUT，修改数据时使用PUT。主体参数使用JSON格式。
• DELETE，删除数据时使用DELETE。

请求返回

返回以HTTP状态码为准。

• 200，执行成功。
• 201，创建成功。
• 401，未验证，没有传递token或token已失效。需要重新获取token(登录)。
• 403，禁止访问，指已登录的用户但没有权限访问。
• 404，请求的资源不存在。
• 409，资源冲突。
• 500，错误返回，服务器出错或业务错误封装。

接口请求成功时， 前端可直接获取数据。

接口请求失败时，返回统一的错误格式。

前端根据HTTP状态码判断请求是否成功，然后获取数据。

错误返回的格式如下：

{
  "title": "",
  "status": 500,
  "detail": "未知的错误！",
  "traceId": "00-d768e1472decd92538cdf0a2120c6a31-a9d7310446ea4a3f-00"
}

ASP.NET Core 请求返回示例

1. 路由定义，约定使用HTTP谓词，不使用Route。 请参见 HTTP谓词模板。
2. 模型绑定，可使用[Frombody]以及[FromRoute]指明请求来源， 参见请求来源，如：

// 修改信息
[HttpPut("{id}")]
public async Task<ActionResult<TEntity?>> UpdateAsync([FromRoute] Guid id, TUpdate form)

1. 关于返回类型，请使用ActionResult<T>或特定类型作为返回类型。

• 正常返回，可直接返回特定类型数据。
• 错误返回,使用Problem()，如：

// 如果错误，使用Problem返回内容
return Problem("未知的错误！", title: "业务错误");

• 404，使用NotFound()，如：

// 如果不存在，返回404
return NotFound("用户名密码不存在");