msumshk/TakeoutSaaS.AdminApi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 完善身份模块文档注释与字段说明

Browse Source
This commit is contained in:
MSuMshk
2025-12-12 11:08:39 +08:00
parent 715cbb3d36
commit 641598de86
36 changed files with 409 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
src/Application/TakeoutSaaS.Application/Identity/Commands/AssignUserRolesCommand.cs
View File

@@ -7,6 +7,13 @@ namespace TakeoutSaaS.Application.Identity.Commands;
/// </summary>
public sealed record AssignUserRolesCommand : IRequest<bool>
{
/// <summary>
/// 用户 ID。
/// </summary>
public long UserId { get; init; }
/// <summary>
/// 角色 ID 集合。
/// </summary>
public long[] RoleIds { get; init; } = Array.Empty<long>();
}

11
src/Application/TakeoutSaaS.Application/Identity/Commands/BindRolePermissionsCommand.cs
View File

@@ -7,7 +7,18 @@ namespace TakeoutSaaS.Application.Identity.Commands;
/// </summary>
public sealed record BindRolePermissionsCommand : IRequest<bool>
{
/// <summary>
/// 角色 ID。
/// </summary>
public long RoleId { get; init; }
/// <summary>
/// 租户 ID（可选，空则取当前上下文）。
/// </summary>
public long? TenantId { get; init; }
/// <summary>
/// 权限 ID 集合。
/// </summary>
public long[] PermissionIds { get; init; } = Array.Empty<long>();
}

55
src/Application/TakeoutSaaS.Application/Identity/Commands/CreateMenuCommand.cs
View File

@@ -9,18 +9,73 @@ namespace TakeoutSaaS.Application.Identity.Commands;
/// </summary>
public sealed record CreateMenuCommand : IRequest<MenuDefinitionDto>
{
/// <summary>
/// 父级菜单 ID。
/// </summary>
public long ParentId { get; init; }
/// <summary>
/// 菜单名称。
/// </summary>
public string Name { get; init; } = string.Empty;
/// <summary>
/// 路由路径。
/// </summary>
public string Path { get; init; } = string.Empty;
/// <summary>
/// 前端组件路径。
/// </summary>
public string Component { get; init; } = string.Empty;
/// <summary>
/// 显示标题。
/// </summary>
public string Title { get; init; } = string.Empty;
/// <summary>
/// 图标。
/// </summary>
public string? Icon { get; init; }
/// <summary>
/// 是否外链。
/// </summary>
public bool IsIframe { get; init; }
/// <summary>
/// 外链地址。
/// </summary>
public string? Link { get; init; }
/// <summary>
/// 是否缓存。
/// </summary>
public bool KeepAlive { get; init; }
/// <summary>
/// 排序序号。
/// </summary>
public int SortOrder { get; init; }
/// <summary>
/// 访问所需权限。
/// </summary>
public IReadOnlyCollection<string> RequiredPermissions { get; init; } = [];
/// <summary>
/// 元信息权限。
/// </summary>
public IReadOnlyCollection<string> MetaPermissions { get; init; } = [];
/// <summary>
/// 元信息角色。
/// </summary>
public IReadOnlyCollection<string> MetaRoles { get; init; } = [];
/// <summary>
/// 按钮权限集合。
/// </summary>
public IReadOnlyCollection<MenuAuthItemDto> AuthList { get; init; } = [];
}

23
src/Application/TakeoutSaaS.Application/Identity/Commands/CreatePermissionCommand.cs
View File

@@ -8,10 +8,33 @@ namespace TakeoutSaaS.Application.Identity.Commands;
/// </summary>
public sealed record CreatePermissionCommand : IRequest<PermissionDto>
{
/// <summary>
/// 父级权限 ID。
/// </summary>
public long ParentId { get; init; } = 0;
/// <summary>
/// 排序序号。
/// </summary>
public int SortOrder { get; init; } = 0;
/// <summary>
/// 权限类型（group/leaf）。
/// </summary>
public string Type { get; init; } = "leaf";
/// <summary>
/// 权限名称。
/// </summary>
public string Name { get; init; } = string.Empty;
/// <summary>
/// 权限编码。
/// </summary>
public string Code { get; init; } = string.Empty;
/// <summary>
/// 描述。
/// </summary>
public string? Description { get; init; }
}

11
src/Application/TakeoutSaaS.Application/Identity/Commands/CreateRoleCommand.cs
View File

@@ -13,7 +13,18 @@ public sealed record CreateRoleCommand : IRequest<RoleDto>
/// </summary>
public long? TenantId { get; init; }
/// <summary>
/// 角色名称。
/// </summary>
public string Name { get; init; } = string.Empty;
/// <summary>
/// 角色编码。
/// </summary>
public string Code { get; init; } = string.Empty;
/// <summary>
/// 描述。
/// </summary>
public string? Description { get; init; }
}

3
src/Application/TakeoutSaaS.Application/Identity/Commands/DeleteMenuCommand.cs
View File

@@ -7,5 +7,8 @@ namespace TakeoutSaaS.Application.Identity.Commands;
/// </summary>
public sealed record DeleteMenuCommand : IRequest<bool>
{
/// <summary>
/// 菜单 ID。
/// </summary>
public long Id { get; init; }
}

3
src/Application/TakeoutSaaS.Application/Identity/Commands/DeletePermissionCommand.cs
View File

@@ -7,5 +7,8 @@ namespace TakeoutSaaS.Application.Identity.Commands;
/// </summary>
public sealed record DeletePermissionCommand : IRequest<bool>
{
/// <summary>
/// 权限 ID。
/// </summary>
public long PermissionId { get; init; }
}

3
src/Application/TakeoutSaaS.Application/Identity/Commands/DeleteRoleCommand.cs
View File

@@ -7,6 +7,9 @@ namespace TakeoutSaaS.Application.Identity.Commands;
/// </summary>
public sealed record DeleteRoleCommand : IRequest<bool>
{
/// <summary>
/// 角色 ID。
/// </summary>
public long RoleId { get; init; }
/// <summary>

59
src/Application/TakeoutSaaS.Application/Identity/Commands/UpdateMenuCommand.cs
View File

@@ -9,19 +9,78 @@ namespace TakeoutSaaS.Application.Identity.Commands;
/// </summary>
public sealed record UpdateMenuCommand : IRequest<MenuDefinitionDto?>
{
/// <summary>
/// 菜单 ID。
/// </summary>
public long Id { get; init; }
/// <summary>
/// 父级菜单 ID。
/// </summary>
public long ParentId { get; init; }
/// <summary>
/// 菜单名称。
/// </summary>
public string Name { get; init; } = string.Empty;
/// <summary>
/// 路由路径。
/// </summary>
public string Path { get; init; } = string.Empty;
/// <summary>
/// 前端组件路径。
/// </summary>
public string Component { get; init; } = string.Empty;
/// <summary>
/// 显示标题。
/// </summary>
public string Title { get; init; } = string.Empty;
/// <summary>
/// 图标。
/// </summary>
public string? Icon { get; init; }
/// <summary>
/// 是否外链。
/// </summary>
public bool IsIframe { get; init; }
/// <summary>
/// 外链地址。
/// </summary>
public string? Link { get; init; }
/// <summary>
/// 是否缓存。
/// </summary>
public bool KeepAlive { get; init; }
/// <summary>
/// 排序序号。
/// </summary>
public int SortOrder { get; init; }
/// <summary>
/// 访问所需权限。
/// </summary>
public IReadOnlyCollection<string> RequiredPermissions { get; init; } = [];
/// <summary>
/// 元信息权限。
/// </summary>
public IReadOnlyCollection<string> MetaPermissions { get; init; } = [];
/// <summary>
/// 元信息角色。
/// </summary>
public IReadOnlyCollection<string> MetaRoles { get; init; } = [];
/// <summary>
/// 按钮权限集合。
/// </summary>
public IReadOnlyCollection<MenuAuthItemDto> AuthList { get; init; } = [];
}

23
src/Application/TakeoutSaaS.Application/Identity/Commands/UpdatePermissionCommand.cs
View File

@@ -8,10 +8,33 @@ namespace TakeoutSaaS.Application.Identity.Commands;
/// </summary>
public sealed record UpdatePermissionCommand : IRequest<PermissionDto?>
{
/// <summary>
/// 权限 ID。
/// </summary>
public long PermissionId { get; init; }
/// <summary>
/// 父级权限 ID。
/// </summary>
public long ParentId { get; init; }
/// <summary>
/// 排序序号。
/// </summary>
public int SortOrder { get; init; }
/// <summary>
/// 权限类型（group/leaf）。
/// </summary>
public string Type { get; init; } = "leaf";
/// <summary>
/// 权限名称。
/// </summary>
public string Name { get; init; } = string.Empty;
/// <summary>
/// 描述。
/// </summary>
public string? Description { get; init; }
}

10
src/Application/TakeoutSaaS.Application/Identity/Commands/UpdateRoleCommand.cs
View File

@@ -8,6 +8,9 @@ namespace TakeoutSaaS.Application.Identity.Commands;
/// </summary>
public sealed record UpdateRoleCommand : IRequest<RoleDto?>
{
/// <summary>
/// 角色 ID。
/// </summary>
public long RoleId { get; init; }
/// <summary>
@@ -15,6 +18,13 @@ public sealed record UpdateRoleCommand : IRequest<RoleDto?>
/// </summary>
public long? TenantId { get; init; }
/// <summary>
/// 角色名称。
/// </summary>
public string Name { get; init; } = string.Empty;
/// <summary>
/// 角色描述。
/// </summary>
public string? Description { get; init; }
}

6
src/Application/TakeoutSaaS.Application/Identity/Contracts/AdminLoginRequest.cs
View File

@@ -7,10 +7,16 @@ namespace TakeoutSaaS.Application.Identity.Contracts;
/// </summary>
public sealed class AdminLoginRequest
{
/// <summary>
/// 账号。
/// </summary>
[Required]
[MaxLength(64)]
public string Account { get; set; } = string.Empty;
/// <summary>
/// 密码。
/// </summary>
[Required]
[MaxLength(128)]
public string Password { get; set; } = string.Empty;

3
src/Application/TakeoutSaaS.Application/Identity/Contracts/RefreshTokenRequest.cs
View File

@@ -7,6 +7,9 @@ namespace TakeoutSaaS.Application.Identity.Contracts;
/// </summary>
public sealed class RefreshTokenRequest
{
/// <summary>
/// 刷新令牌。
/// </summary>
[Required]
[MaxLength(256)]
public string RefreshToken { get; set; } = string.Empty;

15
src/Application/TakeoutSaaS.Application/Identity/Contracts/WeChatLoginRequest.cs
View File

@@ -7,17 +7,32 @@ namespace TakeoutSaaS.Application.Identity.Contracts;
/// </summary>
public sealed class WeChatLoginRequest
{
/// <summary>
/// wx.login 返回的临时 code。
/// </summary>
[Required]
[MaxLength(128)]
public string Code { get; set; } = string.Empty;
/// <summary>
/// 用户昵称。
/// </summary>
[MaxLength(64)]
public string? Nickname { get; set; }
/// <summary>
/// 头像地址。
/// </summary>
[MaxLength(256)]
public string? Avatar { get; set; }
/// <summary>
/// 加密用户数据。
/// </summary>
public string? EncryptedData { get; set; }
/// <summary>
/// 加密向量。
/// </summary>
public string? Iv { get; set; }
}

6
src/Application/TakeoutSaaS.Application/Identity/Handlers/AssignUserRolesCommandHandler.cs
View File

@@ -13,6 +13,12 @@ public sealed class AssignUserRolesCommandHandler(
ITenantProvider tenantProvider)
: IRequestHandler<AssignUserRolesCommand, bool>
{
/// <summary>
/// 处理用户角色分配请求。
/// </summary>
/// <param name="request">分配命令。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>执行结果。</returns>
public async Task<bool> Handle(AssignUserRolesCommand request, CancellationToken cancellationToken)
{
// 1. 获取租户上下文

6
src/Application/TakeoutSaaS.Application/Identity/Handlers/BindRolePermissionsCommandHandler.cs
View File

@@ -13,6 +13,12 @@ public sealed class BindRolePermissionsCommandHandler(
ITenantProvider tenantProvider)
: IRequestHandler<BindRolePermissionsCommand, bool>
{
/// <summary>
/// 处理角色权限绑定请求。
/// </summary>
/// <param name="request">绑定命令。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>执行结果。</returns>
public async Task<bool> Handle(BindRolePermissionsCommand request, CancellationToken cancellationToken)
{
// 1. 获取租户上下文

6
src/Application/TakeoutSaaS.Application/Identity/Handlers/CreatePermissionCommandHandler.cs
View File

@@ -15,6 +15,12 @@ public sealed class CreatePermissionCommandHandler(
ITenantProvider tenantProvider)
: IRequestHandler<CreatePermissionCommand, PermissionDto>
{
/// <summary>
/// 处理创建权限请求。
/// </summary>
/// <param name="request">创建命令。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>创建后的权限 DTO。</returns>
public async Task<PermissionDto> Handle(CreatePermissionCommand request, CancellationToken cancellationToken)
{
// 1. 获取租户上下文

6
src/Application/TakeoutSaaS.Application/Identity/Handlers/CreateRoleCommandHandler.cs
View File

@@ -17,6 +17,12 @@ public sealed class CreateRoleCommandHandler(
ITenantProvider tenantProvider)
: IRequestHandler<CreateRoleCommand, RoleDto>
{
/// <summary>
/// 处理创建角色请求。
/// </summary>
/// <param name="request">创建命令。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>创建后的角色 DTO。</returns>
public async Task<RoleDto> Handle(CreateRoleCommand request, CancellationToken cancellationToken)
{
// 1. 获取租户上下文

6
src/Application/TakeoutSaaS.Application/Identity/Handlers/DeletePermissionCommandHandler.cs
View File

@@ -13,6 +13,12 @@ public sealed class DeletePermissionCommandHandler(
ITenantProvider tenantProvider)
: IRequestHandler<DeletePermissionCommand, bool>
{
/// <summary>
/// 处理删除权限请求。
/// </summary>
/// <param name="request">删除命令。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>执行结果。</returns>
public async Task<bool> Handle(DeletePermissionCommand request, CancellationToken cancellationToken)
{
// 1. 获取租户上下文

6
src/Application/TakeoutSaaS.Application/Identity/Handlers/DeleteRoleCommandHandler.cs
View File

@@ -13,6 +13,12 @@ public sealed class DeleteRoleCommandHandler(
ITenantProvider tenantProvider)
: IRequestHandler<DeleteRoleCommand, bool>
{
/// <summary>
/// 处理删除角色请求。
/// </summary>
/// <param name="request">删除命令。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>执行结果。</returns>
public async Task<bool> Handle(DeleteRoleCommand request, CancellationToken cancellationToken)
{
// 1. 获取租户上下文

6
src/Application/TakeoutSaaS.Application/Identity/Handlers/DeleteRoleTemplateCommandHandler.cs
View File

@@ -10,6 +10,12 @@ namespace TakeoutSaaS.Application.Identity.Handlers;
public sealed class DeleteRoleTemplateCommandHandler(IRoleTemplateRepository roleTemplateRepository)
: IRequestHandler<DeleteRoleTemplateCommand, bool>
{
/// <summary>
/// 处理删除角色模板请求。
/// </summary>
/// <param name="request">删除命令。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>执行结果。</returns>
public async Task<bool> Handle(DeleteRoleTemplateCommand request, CancellationToken cancellationToken)
{
// 1. 查询模板

28
src/Application/TakeoutSaaS.Application/Identity/Handlers/MenuMapper.cs
View File

@@ -9,6 +9,11 @@ namespace TakeoutSaaS.Application.Identity.Handlers;
/// </summary>
internal static class MenuMapper
{
/// <summary>
/// 将菜单实体映射为 DTO。
/// </summary>
/// <param name="entity">菜单实体。</param>
/// <returns>菜单定义 DTO。</returns>
public static MenuDefinitionDto ToDto(MenuDefinition entity)
{
// 1. 解析权限字段
@@ -42,6 +47,11 @@ internal static class MenuMapper
};
}
/// <summary>
/// 将 DTO 字段填充到实体。
/// </summary>
/// <param name="entity">菜单实体。</param>
/// <param name="dto">菜单 DTO。</param>
public static void FillEntity(MenuDefinition entity, MenuDefinitionDto dto)
{
// 1. 赋值基础字段
@@ -65,6 +75,14 @@ internal static class MenuMapper
: JsonSerializer.Serialize(dto.AuthList);
}
/// <summary>
/// 构建或更新菜单实体并返回 DTO。
/// </summary>
/// <param name="existing">已存在的菜单实体。</param>
/// <param name="tenantId">租户 ID。</param>
/// <param name="name">菜单名称。</param>
/// <param name="payload">菜单 DTO 载荷。</param>
/// <returns>菜单定义 DTO。</returns>
public static MenuDefinitionDto FromCommand(MenuDefinition? existing, long tenantId, string name, MenuDefinitionDto payload)
{
// 1. 构造实体
@@ -81,11 +99,21 @@ internal static class MenuMapper
return ToDto(entity);
}
/// <summary>
/// 将权限/角色集合合并为存储字符串。
/// </summary>
/// <param name="codes">编码集合。</param>
/// <returns>逗号分隔字符串。</returns>
public static string JoinCodes(IEnumerable<string> codes)
{
return string.Join(',', codes.Where(x => !string.IsNullOrWhiteSpace(x)).Select(x => x.Trim()).Distinct(StringComparer.OrdinalIgnoreCase));
}
/// <summary>
/// 将逗号分隔编码拆分为集合。
/// </summary>
/// <param name="codes">编码字符串。</param>
/// <returns>编码数组。</returns>
public static string[] SplitCodes(string? codes)
{
if (string.IsNullOrWhiteSpace(codes))

6
src/Application/TakeoutSaaS.Application/Identity/Handlers/PermissionTreeQueryHandler.cs
View File

@@ -14,6 +14,12 @@ public sealed class PermissionTreeQueryHandler(
ITenantProvider tenantProvider)
: IRequestHandler<PermissionTreeQuery, IReadOnlyList<PermissionTreeDto>>
{
/// <summary>
/// 构建权限树。
/// </summary>
/// <param name="request">查询参数。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>权限树列表。</returns>
public async Task<IReadOnlyList<PermissionTreeDto>> Handle(PermissionTreeQuery request, CancellationToken cancellationToken)
{
// 1. 获取租户上下文并查询权限

6
src/Application/TakeoutSaaS.Application/Identity/Handlers/SearchPermissionsQueryHandler.cs
View File

@@ -15,6 +15,12 @@ public sealed class SearchPermissionsQueryHandler(
ITenantProvider tenantProvider)
: IRequestHandler<SearchPermissionsQuery, PagedResult<PermissionDto>>
{
/// <summary>
/// 执行权限分页查询。
/// </summary>
/// <param name="request">查询参数。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>分页结果。</returns>
public async Task<PagedResult<PermissionDto>> Handle(SearchPermissionsQuery request, CancellationToken cancellationToken)
{
// 1. 获取租户上下文并查询权限

6
src/Application/TakeoutSaaS.Application/Identity/Handlers/SearchRolesQueryHandler.cs
View File

@@ -15,6 +15,12 @@ public sealed class SearchRolesQueryHandler(
ITenantProvider tenantProvider)
: IRequestHandler<SearchRolesQuery, PagedResult<RoleDto>>
{
/// <summary>
/// 执行角色分页查询。
/// </summary>
/// <param name="request">查询参数。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>分页结果。</returns>
public async Task<PagedResult<RoleDto>> Handle(SearchRolesQuery request, CancellationToken cancellationToken)
{
// 1. 获取租户上下文并查询角色

6
src/Application/TakeoutSaaS.Application/Identity/Handlers/UpdatePermissionCommandHandler.cs
View File

@@ -14,6 +14,12 @@ public sealed class UpdatePermissionCommandHandler(
ITenantProvider tenantProvider)
: IRequestHandler<UpdatePermissionCommand, PermissionDto?>
{
/// <summary>
/// 执行权限更新。
/// </summary>
/// <param name="request">更新命令。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>更新后的权限 DTO 或 null。</returns>
public async Task<PermissionDto?> Handle(UpdatePermissionCommand request, CancellationToken cancellationToken)
{
// 1. 获取租户上下文并查询权限

6
src/Application/TakeoutSaaS.Application/Identity/Handlers/UpdateRoleCommandHandler.cs
View File

@@ -14,6 +14,12 @@ public sealed class UpdateRoleCommandHandler(
ITenantProvider tenantProvider)
: IRequestHandler<UpdateRoleCommand, RoleDto?>
{
/// <summary>
/// 执行角色更新。
/// </summary>
/// <param name="request">更新命令。</param>
/// <param name="cancellationToken">取消标记。</param>
/// <returns>更新后的角色 DTO 或 null。</returns>
public async Task<RoleDto?> Handle(UpdateRoleCommand request, CancellationToken cancellationToken)
{
// 1. 获取租户上下文并查询角色

15
src/Application/TakeoutSaaS.Application/Identity/Queries/SearchPermissionsQuery.cs
View File

@@ -9,9 +9,24 @@ namespace TakeoutSaaS.Application.Identity.Queries;
/// </summary>
public sealed class SearchPermissionsQuery : IRequest<PagedResult<PermissionDto>>
{
/// <summary>
/// 搜索关键字。
/// </summary>
public string? Keyword { get; init; }
/// <summary>
/// 页码（从 1 开始）。
/// </summary>
public int Page { get; init; } = 1;
/// <summary>
/// 每页条数。
/// </summary>
public int PageSize { get; init; } = 20;
/// <summary>
/// 排序字段。
/// </summary>
public string? SortBy { get; init; }
/// <summary>
/// 是否降序。
/// </summary>
public bool SortDescending { get; init; } = true;
}

15
src/Application/TakeoutSaaS.Application/Identity/Queries/SearchRolesQuery.cs
View File

@@ -14,9 +14,24 @@ public sealed class SearchRolesQuery : IRequest<PagedResult<RoleDto>>
/// </summary>
public long? TenantId { get; init; }
/// <summary>
/// 搜索关键字。
/// </summary>
public string? Keyword { get; init; }
/// <summary>
/// 页码（从 1 开始）。
/// </summary>
public int Page { get; init; } = 1;
/// <summary>
/// 每页条数。
/// </summary>
public int PageSize { get; init; } = 20;
/// <summary>
/// 排序字段。
/// </summary>
public string? SortBy { get; init; }
/// <summary>
/// 是否降序。
/// </summary>
public bool SortDescending { get; init; } = true;
}

13
src/Core/TakeoutSaaS.Shared.Web/Filters/ApiResponseResultFilter.cs
View File

@@ -12,20 +12,29 @@ namespace TakeoutSaaS.Shared.Web.Filters;
/// </summary>
public sealed class ApiResponseResultFilter : IAsyncResultFilter
{
/// <summary>
/// 执行结果过滤，将 ApiResponse 映射为对应 HTTP 状态码。
/// </summary>
/// <param name="context">结果执行上下文。</param>
/// <param name="next">后续委托。</param>
/// <returns>异步任务。</returns>
public Task OnResultExecutionAsync(ResultExecutingContext context, ResultExecutionDelegate next)
{
// 1. 仅处理 ObjectResult
// 只处理 ObjectResult 类型的结果
if (context.Result is not ObjectResult objectResult)
{
return next();
}
// 2. 结果为空直接跳过
var value = objectResult.Value;
if (value == null)
{
return next();
}
// 3. 确认类型为 ApiResponse<T>
// 检查是否是 ApiResponse<T> 类型
var valueType = value.GetType();
if (!IsApiResponseType(valueType))
@@ -33,6 +42,7 @@ public sealed class ApiResponseResultFilter : IAsyncResultFilter
return next();
}
// 4. 读取 Success 与 Code
// 使用反射获取 Success 和 Code 属性
// 注意：由于已通过 IsApiResponseType 检查，属性名是固定的
const string successPropertyName = "Success";
@@ -48,9 +58,11 @@ public sealed class ApiResponseResultFilter : IAsyncResultFilter
var success = (bool)(successProperty.GetValue(value) ?? false);
var code = (int)(codeProperty.GetValue(value) ?? 200);
// 5. 映射 HTTP 状态码
// 根据 Success 和 Code 设置 HTTP 状态码
var statusCode = success ? MapSuccessCode(code) : MapErrorCode(code);
// 6. 回写状态码
// 更新 ObjectResult 的状态码
objectResult.StatusCode = statusCode;
@@ -101,4 +113,3 @@ public sealed class ApiResponseResultFilter : IAsyncResultFilter
};
}
}

5
src/Core/TakeoutSaaS.Shared.Web/Filters/ValidateModelAttribute.cs
View File

@@ -10,8 +10,13 @@ namespace TakeoutSaaS.Shared.Web.Filters;
/// </summary>
public sealed class ValidateModelAttribute : ActionFilterAttribute
{
/// <summary>
/// 在 Action 执行前拦截模型验证错误。
/// </summary>
/// <param name="context">执行上下文。</param>
public override void OnActionExecuting(ActionExecutingContext context)
{
// 1. 模型验证未通过则返回 422
if (!context.ModelState.IsValid)
{
var errors = context.ModelState

9
src/Core/TakeoutSaaS.Shared.Web/Middleware/CorrelationIdMiddleware.cs
View File

@@ -15,8 +15,13 @@ public sealed class CorrelationIdMiddleware(RequestDelegate next, ILogger<Correl
private const string SpanHeader = "X-Span-Id";
private const string RequestHeader = "X-Request-Id";
/// <summary>
/// 管道入口，确保 TraceId/SpanId 贯穿请求。
/// </summary>
/// <param name="context">HTTP 上下文。</param>
public async Task InvokeAsync(HttpContext context)
{
// 1. 确保活动存在并启动
var ownsActivity = Activity.Current is null;
var activity = Activity.Current ?? new Activity("TakeoutSaaS.Request");
@@ -26,6 +31,7 @@ public sealed class CorrelationIdMiddleware(RequestDelegate next, ILogger<Correl
activity.Start();
}
// 2. 生成/解析 TraceId、SpanId
var traceId = activity.TraceId.ToString();
var spanId = activity.SpanId.ToString();
@@ -34,6 +40,7 @@ public sealed class CorrelationIdMiddleware(RequestDelegate next, ILogger<Correl
traceId = ResolveTraceId(context);
}
// 3. 写入上下文与响应头
context.TraceIdentifier = traceId;
TraceContext.TraceId = traceId;
TraceContext.SpanId = spanId;
@@ -45,6 +52,7 @@ public sealed class CorrelationIdMiddleware(RequestDelegate next, ILogger<Correl
return Task.CompletedTask;
});
// 4. 带 Scope 调用后续中间件
using (logger.BeginScope(new Dictionary<string, object>
{
["TraceId"] = traceId,
@@ -57,6 +65,7 @@ public sealed class CorrelationIdMiddleware(RequestDelegate next, ILogger<Correl
}
finally
{
// 5. 清理上下文与活动
TraceContext.Clear();
if (ownsActivity)
{

9
src/Core/TakeoutSaaS.Shared.Web/Middleware/ExceptionHandlingMiddleware.cs
View File

@@ -31,6 +31,10 @@ public sealed class ExceptionHandlingMiddleware(RequestDelegate next, ILogger<Ex
DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
};
/// <summary>
/// 中间件入口，捕获并统一处理异常。
/// </summary>
/// <param name="context">HTTP 上下文。</param>
public async Task InvokeAsync(HttpContext context)
{
try
@@ -39,17 +43,21 @@ public sealed class ExceptionHandlingMiddleware(RequestDelegate next, ILogger<Ex
}
catch (Exception ex)
{
// 1. 记录异常
logger.LogError(ex, "未处理异常：{Message}", ex.Message);
// 2. 返回统一错误响应
await HandleExceptionAsync(context, ex);
}
}
private Task HandleExceptionAsync(HttpContext context, Exception exception)
{
// 1. 构建错误响应与状态码
var (statusCode, response) = BuildErrorResponse(exception);
if (environment.IsDevelopment())
{
// 2. 开发环境附加细节
response = response with
{
Message = exception.Message,
@@ -61,6 +69,7 @@ public sealed class ExceptionHandlingMiddleware(RequestDelegate next, ILogger<Ex
};
}
// 3. 写入响应
context.Response.StatusCode = statusCode;
context.Response.ContentType = "application/json";
return context.Response.WriteAsJsonAsync(response, SerializerOptions);

6
src/Core/TakeoutSaaS.Shared.Web/Middleware/RequestLoggingMiddleware.cs
View File

@@ -10,8 +10,13 @@ namespace TakeoutSaaS.Shared.Web.Middleware;
/// </summary>
public sealed class RequestLoggingMiddleware(RequestDelegate next, ILogger<RequestLoggingMiddleware> logger)
{
/// <summary>
/// 记录请求日志并调用后续中间件。
/// </summary>
/// <param name="context">HTTP 上下文。</param>
public async Task InvokeAsync(HttpContext context)
{
// 1. 启动计时
var stopwatch = Stopwatch.StartNew();
try
{
@@ -19,6 +24,7 @@ public sealed class RequestLoggingMiddleware(RequestDelegate next, ILogger<Reque
}
finally
{
// 2. 结束计时并输出日志
stopwatch.Stop();
var traceId = TraceContext.TraceId ?? context.TraceIdentifier;
var spanId = TraceContext.SpanId ?? Activity.Current?.SpanId.ToString() ?? string.Empty;

7
src/Core/TakeoutSaaS.Shared.Web/Middleware/SecurityHeadersMiddleware.cs
View File

@@ -7,14 +7,19 @@ namespace TakeoutSaaS.Shared.Web.Middleware;
/// </summary>
public sealed class SecurityHeadersMiddleware(RequestDelegate next)
{
/// <summary>
/// 设置基础安全响应头。
/// </summary>
/// <param name="context">HTTP 上下文。</param>
public async Task InvokeAsync(HttpContext context)
{
// 1. 写入安全响应头
var headers = context.Response.Headers;
headers["X-Content-Type-Options"] = "nosniff";
headers["X-Frame-Options"] = "DENY";
headers["X-XSS-Protection"] = "1; mode=block";
headers["Referrer-Policy"] = "no-referrer";
// 2. 继续后续管道
await next(context);
}
}