docs: 补全全部缺失的 XML 文档注释（中文）
- 为全部 5 个项目（Avalonia-API、Avalonia-Common、Avalonia-EFCore、 Avalonia-PC、Avalonia-Services）中缺失注释的类、方法、属性、字段、 接口成员等补全中文 XML 文档注释 - 共修改约 37 个文件，补全约 220+ 处注释 - 修复 ServiceEndpointCollection.cs 中 MapDelete<TService> 语法错误 - 修复 PcAuthService.cs 中 const prefix 位置错乱导致编译失败的问题 - 扫描结果：缺失项 0 - 构建结果：4/4 项目编译通过
This commit is contained in:
@@ -10,9 +10,13 @@ namespace Avalonia_Services.Core
|
||||
/// </summary>
|
||||
public sealed class GlobalExceptionFilter : IEndpointFilter
|
||||
{
|
||||
/// <summary>
|
||||
/// 是否在错误响应中包含异常详情。
|
||||
/// </summary>
|
||||
private readonly bool _includeDetails;
|
||||
|
||||
/// <summary>
|
||||
/// 初始化全局异常过滤器。
|
||||
/// </summary>
|
||||
/// <param name="includeDetails">是否在响应中包含异常详情（开发环境建议 true，生产环境 false）</param>
|
||||
public GlobalExceptionFilter(bool includeDetails = false)
|
||||
@@ -20,6 +24,11 @@ namespace Avalonia_Services.Core
|
||||
_includeDetails = includeDetails;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 执行过滤器逻辑：包裹下一个委托，捕获所有未处理异常并转换为统一错误响应。
|
||||
/// </summary>
|
||||
/// <param name="context">请求上下文。</param>
|
||||
/// <param name="next">管道中的下一个委托。</param>
|
||||
public async Task InvokeAsync(ServiceEndpointContext context, EndpointFilterDelegate next)
|
||||
{
|
||||
try
|
||||
@@ -73,6 +82,11 @@ namespace Avalonia_Services.Core
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 记录异常日志，优先使用 Serilog，不可用时回退到 Console。
|
||||
/// </summary>
|
||||
/// <param name="context">请求上下文。</param>
|
||||
/// <param name="ex">异常对象。</param>
|
||||
private static void LogException(ServiceEndpointContext context, Exception ex)
|
||||
{
|
||||
try
|
||||
|
||||
@@ -23,13 +23,13 @@ namespace Avalonia_Services.Core
|
||||
/// </summary>
|
||||
public sealed class AnonymousAuthService : IAuthService
|
||||
{
|
||||
/// <inheritdoc />
|
||||
public Task<ClaimsPrincipal?> AuthenticateAsync(ServiceEndpointContext context)
|
||||
{
|
||||
// 匿名用户，始终通过
|
||||
var identity = new ClaimsIdentity("anonymous");
|
||||
return Task.FromResult<ClaimsPrincipal?>(new ClaimsPrincipal(identity));
|
||||
}
|
||||
|
||||
/// <inheritdoc />
|
||||
public Task<bool> AuthorizeAsync(ClaimsPrincipal user, string policy)
|
||||
{
|
||||
|
||||
@@ -25,13 +25,21 @@ namespace Avalonia_Services.Core
|
||||
/// </summary>
|
||||
internal sealed class AnonymousEndpointFilter : IEndpointFilter
|
||||
{
|
||||
/// <summary>
|
||||
/// 匿名过滤器的委托实现。
|
||||
/// </summary>
|
||||
private readonly Func<ServiceEndpointContext, EndpointFilterDelegate, Task> _filter;
|
||||
|
||||
/// <summary>
|
||||
/// 使用匿名函数创建过滤器。
|
||||
/// </summary>
|
||||
/// <param name="filter">过滤器委托。</param>
|
||||
public AnonymousEndpointFilter(Func<ServiceEndpointContext, EndpointFilterDelegate, Task> filter)
|
||||
{
|
||||
_filter = filter;
|
||||
}
|
||||
|
||||
/// <inheritdoc />
|
||||
public Task InvokeAsync(ServiceEndpointContext context, EndpointFilterDelegate next)
|
||||
{
|
||||
return _filter(context, next);
|
||||
|
||||
@@ -5,11 +5,17 @@ using Microsoft.Extensions.DependencyInjection;
|
||||
|
||||
namespace Avalonia_Services.Core
|
||||
{
|
||||
/// <summary>
|
||||
/// 端点挂载的宿主目标。
|
||||
/// </summary>
|
||||
[Flags]
|
||||
public enum EndpointHostTarget
|
||||
{
|
||||
/// <summary>挂载到 Avalonia-API（ASP.NET Core Web API）。</summary>
|
||||
Api = 1,
|
||||
/// <summary>挂载到 Avalonia-PC（桌面 WebView）。</summary>
|
||||
Pc = 2,
|
||||
/// <summary>同时挂载到 API 和 PC。</summary>
|
||||
All = Api | Pc,
|
||||
}
|
||||
|
||||
@@ -69,6 +75,15 @@ namespace Avalonia_Services.Core
|
||||
return this;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 设置端点的 OpenAPI 元数据（标签、摘要、描述、请求/响应类型）。
|
||||
/// </summary>
|
||||
/// <param name="tag">OpenAPI 分组标签。</param>
|
||||
/// <param name="summary">简要摘要。</param>
|
||||
/// <param name="description">详细描述。</param>
|
||||
/// <param name="requestType">请求体类型。</param>
|
||||
/// <param name="responseType">成功响应类型。</param>
|
||||
/// <returns>当前端点实例（Fluent API）。</returns>
|
||||
public ServiceEndpoint WithOpenApi(
|
||||
string tag,
|
||||
string summary,
|
||||
@@ -122,6 +137,11 @@ namespace Avalonia_Services.Core
|
||||
return this;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 判断端点是否支持指定的宿主目标。
|
||||
/// </summary>
|
||||
/// <param name="host">要检查的宿主目标。</param>
|
||||
/// <returns>是否支持。</returns>
|
||||
public bool SupportsHost(EndpointHostTarget host)
|
||||
{
|
||||
return (HostTarget & host) != 0;
|
||||
@@ -136,6 +156,11 @@ namespace Avalonia_Services.Core
|
||||
/// <summary>所有已注册的端点</summary>
|
||||
public List<ServiceEndpoint> Endpoints { get; } = new();
|
||||
|
||||
/// <summary>
|
||||
/// 获取指定宿主目标的所有端点。
|
||||
/// </summary>
|
||||
/// <param name="host">宿主目标。</param>
|
||||
/// <returns>匹配的端点集合。</returns>
|
||||
public IEnumerable<ServiceEndpoint> ForHost(EndpointHostTarget host)
|
||||
{
|
||||
return Endpoints.Where(endpoint => endpoint.SupportsHost(host));
|
||||
@@ -152,6 +177,13 @@ namespace Avalonia_Services.Core
|
||||
return AddEndpoint(pattern, "GET", handler);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 注册一个带服务依赖注入的 GET 端点。
|
||||
/// </summary>
|
||||
/// <typeparam name="TService">服务类型。</typeparam>
|
||||
/// <param name="pattern">路由路径。</param>
|
||||
/// <param name="handler">接受服务实例和上下文的处理器。</param>
|
||||
/// <returns>已注册的端点实例。</returns>
|
||||
public ServiceEndpoint MapGet<TService>(
|
||||
string pattern,
|
||||
Func<TService, ServiceEndpointContext, Task<object?>> handler)
|
||||
@@ -168,6 +200,13 @@ namespace Avalonia_Services.Core
|
||||
return AddEndpoint(pattern, "POST", handler);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 注册一个带服务依赖注入的 POST 端点。
|
||||
/// </summary>
|
||||
/// <typeparam name="TService">服务类型。</typeparam>
|
||||
/// <param name="pattern">路由路径。</param>
|
||||
/// <param name="handler">接受服务实例和上下文的处理器。</param>
|
||||
/// <returns>已注册的端点实例。</returns>
|
||||
public ServiceEndpoint MapPost<TService>(
|
||||
string pattern,
|
||||
Func<TService, ServiceEndpointContext, Task<object?>> handler)
|
||||
@@ -184,6 +223,13 @@ namespace Avalonia_Services.Core
|
||||
return AddEndpoint(pattern, "PUT", handler);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 注册一个带服务依赖注入的 PUT 端点。
|
||||
/// </summary>
|
||||
/// <typeparam name="TService">服务类型。</typeparam>
|
||||
/// <param name="pattern">路由路径。</param>
|
||||
/// <param name="handler">接受服务实例和上下文的处理器。</param>
|
||||
/// <returns>已注册的端点实例。</returns>
|
||||
public ServiceEndpoint MapPut<TService>(
|
||||
string pattern,
|
||||
Func<TService, ServiceEndpointContext, Task<object?>> handler)
|
||||
@@ -200,6 +246,13 @@ namespace Avalonia_Services.Core
|
||||
return AddEndpoint(pattern, "DELETE", handler);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 注册一个带服务依赖注入的 DELETE 端点。
|
||||
/// </summary>
|
||||
/// <typeparam name="TService">服务类型。</typeparam>
|
||||
/// <param name="pattern">路由路径。</param>
|
||||
/// <param name="handler">接受服务实例和上下文的处理器。</param>
|
||||
/// <returns>已注册的端点实例。</returns>
|
||||
public ServiceEndpoint MapDelete<TService>(
|
||||
string pattern,
|
||||
Func<TService, ServiceEndpointContext, Task<object?>> handler)
|
||||
@@ -226,6 +279,13 @@ namespace Avalonia_Services.Core
|
||||
return this;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 内部方法，创建端点并添加到集合。
|
||||
/// </summary>
|
||||
/// <param name="pattern">路由路径。</param>
|
||||
/// <param name="method">HTTP 方法。</param>
|
||||
/// <param name="handler">端点处理器。</param>
|
||||
/// <returns>已创建的端点实例。</returns>
|
||||
private ServiceEndpoint AddEndpoint(string pattern, string method, Func<ServiceEndpointContext, Task<object?>> handler)
|
||||
{
|
||||
var endpoint = new ServiceEndpoint
|
||||
@@ -238,6 +298,12 @@ namespace Avalonia_Services.Core
|
||||
return endpoint;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// 创建自动从 DI 解析服务实例并调用处理器的委托包装。
|
||||
/// </summary>
|
||||
/// <typeparam name="TService">服务类型。</typeparam>
|
||||
/// <param name="handler">接受服务实例和上下文的处理器。</param>
|
||||
/// <returns>包装后的处理器委托。</returns>
|
||||
private static Func<ServiceEndpointContext, Task<object?>> CreateServiceHandler<TService>(
|
||||
Func<TService, ServiceEndpointContext, Task<object?>> handler)
|
||||
where TService : notnull
|
||||
|
||||
Reference in New Issue
Block a user