admin777/AvaloniaStack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 完善统一端点响应与请求绑定框架

Browse Source 
- 新增 IApiResponse 统一响应契约，覆盖普通响应和分页响应
- 扩展端点映射，支持 IApiResponse 和带请求 DTO 的 MapXxx 重载
- 增加 Body、Query、Route Values 到请求 DTO 的自动绑定
- 增加 PC 端路由模式匹配，支持 {id} 和 {id:int}
- API 与 PC 端点上下文补充路由参数传递
- 调整 OpenAPI 请求类型处理，避免 GET/DELETE 被标记为 JSON Body
- 鉴权端点迁移到强类型请求绑定和 IApiResponse 返回
- 增加统一端点文件流响应支持
This commit is contained in:
admin777
2026-05-22 11:42:38 +08:00
parent e72bff954b
commit 5cdc7052e0
13 changed files with 414 additions and 82 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Avalonia-Services/Core/FileStreamResponse.cs
+11
View File
@@ -0,0 +1,11 @@
namespace Avalonia_Services.Core
{
/// <summary>
/// 文件流响应 —— 管道检测到此类型时将返回原始文件而非 JSON。
/// </summary>
public sealed record FileStreamResponse(
string FilePath,
string FileName,
string ContentType,
DateTime LastModified);
}
Avalonia-Services/Core/ServiceEndpointCollection.cs
+168
View File
@@ -1,3 +1,4 @@
using Avalonia_Common.Core;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
@@ -177,6 +178,14 @@ namespace Avalonia_Services.Core
return AddEndpoint(pattern, "GET", handler);
}
/// <summary>
/// 注册一个返回统一响应契约的 GET 端点。
/// </summary>
public ServiceEndpoint MapGet(string pattern, Func<ServiceEndpointContext, Task<IApiResponse>> handler)
{
return MapGet(pattern, CreateApiResponseHandler(handler));
}
/// <summary>
/// 注册一个带服务依赖注入的 GET 端点。
/// </summary>
@@ -192,6 +201,33 @@ namespace Avalonia_Services.Core
return MapGet(pattern, CreateServiceHandler(handler));
}
/// <summary>
/// 注册一个带服务依赖注入且返回统一响应契约的 GET 端点。
/// </summary>
public ServiceEndpoint MapGet<TService>(
string pattern,
Func<TService, ServiceEndpointContext, Task<IApiResponse>> handler)
where TService : notnull
{
return MapGet(pattern, CreateServiceHandler(handler));
}
/// <summary>
/// 注册一个带查询请求 DTO 和服务依赖注入的 GET 端点。
/// </summary>
public ServiceEndpoint MapGet<TService, TRequest>(
string pattern,
Func<TService, TRequest, ServiceEndpointContext, Task<IApiResponse>> handler)
where TService : notnull
{
var endpoint = MapGet(
pattern,
CreateServiceHandler<TService>((service, ctx) =>
handler(service, ServiceRequestBinder.BindQuery<TRequest>(ctx), ctx)));
endpoint.OpenApiRequestType ??= typeof(TRequest);
return endpoint;
}
/// <summary>
/// 注册一个 POST 端点。
/// </summary>
@@ -200,6 +236,14 @@ namespace Avalonia_Services.Core
return AddEndpoint(pattern, "POST", handler);
}
/// <summary>
/// 注册一个返回统一响应契约的 POST 端点。
/// </summary>
public ServiceEndpoint MapPost(string pattern, Func<ServiceEndpointContext, Task<IApiResponse>> handler)
{
return MapPost(pattern, CreateApiResponseHandler(handler));
}
/// <summary>
/// 注册一个带服务依赖注入的 POST 端点。
/// </summary>
@@ -215,6 +259,33 @@ namespace Avalonia_Services.Core
return MapPost(pattern, CreateServiceHandler(handler));
}
/// <summary>
/// 注册一个带服务依赖注入且返回统一响应契约的 POST 端点。
/// </summary>
public ServiceEndpoint MapPost<TService>(
string pattern,
Func<TService, ServiceEndpointContext, Task<IApiResponse>> handler)
where TService : notnull
{
return MapPost(pattern, CreateServiceHandler(handler));
}
/// <summary>
/// 注册一个带 JSON 请求 DTO 和服务依赖注入的 POST 端点。
/// </summary>
public ServiceEndpoint MapPost<TService, TRequest>(
string pattern,
Func<TService, TRequest, ServiceEndpointContext, Task<IApiResponse>> handler)
where TService : notnull
{
var endpoint = MapPost(
pattern,
CreateServiceHandler<TService>((service, ctx) =>
handler(service, ServiceRequestBinder.BindBody<TRequest>(ctx), ctx)));
endpoint.OpenApiRequestType ??= typeof(TRequest);
return endpoint;
}
/// <summary>
/// 注册一个 PUT 端点。
/// </summary>
@@ -223,6 +294,14 @@ namespace Avalonia_Services.Core
return AddEndpoint(pattern, "PUT", handler);
}
/// <summary>
/// 注册一个返回统一响应契约的 PUT 端点。
/// </summary>
public ServiceEndpoint MapPut(string pattern, Func<ServiceEndpointContext, Task<IApiResponse>> handler)
{
return MapPut(pattern, CreateApiResponseHandler(handler));
}
/// <summary>
/// 注册一个带服务依赖注入的 PUT 端点。
/// </summary>
@@ -238,6 +317,33 @@ namespace Avalonia_Services.Core
return MapPut(pattern, CreateServiceHandler(handler));
}
/// <summary>
/// 注册一个带服务依赖注入且返回统一响应契约的 PUT 端点。
/// </summary>
public ServiceEndpoint MapPut<TService>(
string pattern,
Func<TService, ServiceEndpointContext, Task<IApiResponse>> handler)
where TService : notnull
{
return MapPut(pattern, CreateServiceHandler(handler));
}
/// <summary>
/// 注册一个带 JSON 请求 DTO 和服务依赖注入的 PUT 端点。
/// </summary>
public ServiceEndpoint MapPut<TService, TRequest>(
string pattern,
Func<TService, TRequest, ServiceEndpointContext, Task<IApiResponse>> handler)
where TService : notnull
{
var endpoint = MapPut(
pattern,
CreateServiceHandler<TService>((service, ctx) =>
handler(service, ServiceRequestBinder.BindBody<TRequest>(ctx), ctx)));
endpoint.OpenApiRequestType ??= typeof(TRequest);
return endpoint;
}
/// <summary>
/// 注册一个 DELETE 端点。
/// </summary>
@@ -246,6 +352,14 @@ namespace Avalonia_Services.Core
return AddEndpoint(pattern, "DELETE", handler);
}
/// <summary>
/// 注册一个返回统一响应契约的 DELETE 端点。
/// </summary>
public ServiceEndpoint MapDelete(string pattern, Func<ServiceEndpointContext, Task<IApiResponse>> handler)
{
return MapDelete(pattern, CreateApiResponseHandler(handler));
}
/// <summary>
/// 注册一个带服务依赖注入的 DELETE 端点。
/// </summary>
@@ -261,6 +375,33 @@ namespace Avalonia_Services.Core
return MapDelete(pattern, CreateServiceHandler(handler));
}
/// <summary>
/// 注册一个带服务依赖注入且返回统一响应契约的 DELETE 端点。
/// </summary>
public ServiceEndpoint MapDelete<TService>(
string pattern,
Func<TService, ServiceEndpointContext, Task<IApiResponse>> handler)
where TService : notnull
{
return MapDelete(pattern, CreateServiceHandler(handler));
}
/// <summary>
/// 注册一个带查询请求 DTO 和服务依赖注入的 DELETE 端点。
/// </summary>
public ServiceEndpoint MapDelete<TService, TRequest>(
string pattern,
Func<TService, TRequest, ServiceEndpointContext, Task<IApiResponse>> handler)
where TService : notnull
{
var endpoint = MapDelete(
pattern,
CreateServiceHandler<TService>((service, ctx) =>
handler(service, ServiceRequestBinder.BindQuery<TRequest>(ctx), ctx)));
endpoint.OpenApiRequestType ??= typeof(TRequest);
return endpoint;
}
/// <summary>
/// 添加全局过滤器（作用于所有端点）。
/// </summary>
@@ -318,6 +459,33 @@ namespace Avalonia_Services.Core
return await handler(service, ctx);
};
}
/// <summary>
/// 将统一响应契约适配为端点集合内部使用的异构响应类型。
/// </summary>
private static Func<ServiceEndpointContext, Task<object?>> CreateApiResponseHandler(
Func<ServiceEndpointContext, Task<IApiResponse>> handler)
{
return async ctx => await handler(ctx);
}
/// <summary>
/// 为服务端点创建统一响应契约的 DI 包装。
/// </summary>
private static Func<ServiceEndpointContext, Task<IApiResponse>> CreateServiceHandler<TService>(
Func<TService, ServiceEndpointContext, Task<IApiResponse>> handler)
where TService : notnull
{
return async ctx =>
{
var serviceProvider = ctx.Items["ServiceProvider"] as IServiceProvider
?? throw new InvalidOperationException("ServiceProvider 未注入。");
await using var scope = serviceProvider.CreateAsyncScope();
var service = scope.ServiceProvider.GetRequiredService<TService>();
return await handler(service, ctx);
};
}
}
/// <summary>
Avalonia-Services/Core/ServiceEndpointContext.cs
+5
View File
@@ -32,6 +32,11 @@ namespace Avalonia_Services.Core
/// </summary>
public Dictionary<string, string> Query { get; init; } = new(StringComparer.OrdinalIgnoreCase);
/// <summary>
/// 路由路径参数。
/// </summary>
public Dictionary<string, string> RouteValues { get; init; } = new(StringComparer.OrdinalIgnoreCase);
/// <summary>
/// 响应状态码
/// </summary>
Avalonia-Services/Core/ServiceEndpointPatternMatcher.cs
+75
View File
@@ -0,0 +1,75 @@
namespace Avalonia_Services.Core
{
/// <summary>
/// Matches unified endpoint patterns and extracts simple route values.
/// </summary>
internal static class ServiceEndpointPatternMatcher
{
/// <summary>
/// Match literal segments and single-segment route parameters such as {id} or {id:int}.
/// </summary>
public static bool TryMatch(
string pattern,
string path,
out Dictionary<string, string> routeValues)
{
routeValues = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
var patternSegments = SplitSegments(pattern);
var pathSegments = SplitSegments(path);
if (patternSegments.Length != pathSegments.Length)
{
return false;
}
for (var index = 0; index < patternSegments.Length; index++)
{
var patternSegment = patternSegments[index];
var pathSegment = pathSegments[index];
if (TryGetParameterName(patternSegment, out var parameterName))
{
if (!MatchesConstraint(patternSegment, pathSegment))
{
return false;
}
routeValues[parameterName] = Uri.UnescapeDataString(pathSegment);
continue;
}
if (!string.Equals(patternSegment, pathSegment, StringComparison.OrdinalIgnoreCase))
{
return false;
}
}
return true;
}
private static string[] SplitSegments(string value)
{
return value.Split('/', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
}
private static bool TryGetParameterName(string segment, out string parameterName)
{
parameterName = string.Empty;
if (segment.Length < 3 || segment[0] != '{' || segment[^1] != '}')
{
return false;
}
var token = segment[1..^1];
var constraintIndex = token.IndexOf(':');
parameterName = constraintIndex >= 0 ? token[..constraintIndex] : token;
return !string.IsNullOrWhiteSpace(parameterName);
}
private static bool MatchesConstraint(string segment, string value)
{
return !segment.EndsWith(":int}", StringComparison.OrdinalIgnoreCase)
|| int.TryParse(value, out _);
}
}
}
Avalonia-Services/Core/ServiceRequestBinder.cs
+53
View File
@@ -0,0 +1,53 @@
using System.Text.Json;
using System.Text.Json.Serialization;
namespace Avalonia_Services.Core
{
/// <summary>
/// Binds unified endpoint request models from JSON bodies or query parameters.
/// </summary>
internal static class ServiceRequestBinder
{
private static readonly JsonSerializerOptions JsonOptions = new(JsonSerializerDefaults.Web)
{
NumberHandling = JsonNumberHandling.AllowReadingFromString,
};
/// <summary>
/// Bind a JSON request body. Empty bodies are treated as an empty JSON object.
/// </summary>
public static T BindBody<T>(ServiceEndpointContext context)
{
var json = string.IsNullOrWhiteSpace(context.Body) ? "{}" : context.Body;
return Deserialize<T>(json, "body");
}
/// <summary>
/// Bind route and query parameters to a request DTO.
/// </summary>
public static T BindQuery<T>(ServiceEndpointContext context)
{
var values = new Dictionary<string, string>(context.Query, StringComparer.OrdinalIgnoreCase);
foreach (var routeValue in context.RouteValues)
{
values[routeValue.Key] = routeValue.Value;
}
var json = JsonSerializer.Serialize(values, JsonOptions);
return Deserialize<T>(json, "query");
}
private static T Deserialize<T>(string json, string source)
{
try
{
return JsonSerializer.Deserialize<T>(json, JsonOptions)
?? throw new ArgumentException($"Request {source} cannot be bound to {typeof(T).Name}.");
}
catch (JsonException ex)
{
throw new ArgumentException($"Request {source} cannot be bound to {typeof(T).Name}.", ex);
}
}
}
}
Avalonia-Services/Endpoints/AppEndpoints.cs
+3 -3
View File
@@ -63,7 +63,7 @@ namespace Avalonia_Services.Endpoints
/// <summary>
/// 从数据库查询天气预报（优先数据库，回退到内存生成）。
/// </summary>
private static async Task<object?> GetWeatherForecastsAsync(ServiceEndpointContext ctx)
private static async Task<IApiResponse> GetWeatherForecastsAsync(ServiceEndpointContext ctx)
{
var sp = ctx.Items["ServiceProvider"] as IServiceProvider;
@@ -94,7 +94,7 @@ namespace Avalonia_Services.Endpoints
/// </summary>
/// <param name="ctx">服务端点上下文。</param>
/// <returns>用户信息。</returns>
private static async Task<object?> GetUserFromDatabaseAsync(ServiceEndpointContext ctx)
private static async Task<IApiResponse> GetUserFromDatabaseAsync(ServiceEndpointContext ctx)
{
var sp = ctx.Items["ServiceProvider"] as IServiceProvider;
@@ -119,7 +119,7 @@ namespace Avalonia_Services.Endpoints
/// </summary>
/// <param name="ctx">服务端点上下文。</param>
/// <returns>处理结果。</returns>
private static async Task<object?> ProcessDataAsync(ServiceEndpointContext ctx)
private static async Task<IApiResponse> ProcessDataAsync(ServiceEndpointContext ctx)
{
var sp = ctx.Items["ServiceProvider"] as IServiceProvider;
Avalonia-Services/Endpoints/AuthEndpoints.cs
+18 -6
View File
@@ -16,17 +16,23 @@ namespace Avalonia_Services.Endpoints
{
builder.ConfigureEndpoints(endpoints =>
{
endpoints.MapPost<IApiAuthEndpointService>("api/auth/login", (service, ctx) => service.LoginAsync(ctx))
endpoints.MapPost<IApiAuthEndpointService, ApiLoginRequest>(
"api/auth/login",
(service, request, ctx) => service.LoginAsync(request, ctx))
.WithName("ApiLogin")
.WithOpenApi("Auth", "API 登录，返回 access token 和 refresh token。", "", typeof(ApiLoginRequest), typeof(AuthTokenResponse))
.ApiOnly();
endpoints.MapPost<IApiAuthEndpointService>("api/auth/refresh", (service, ctx) => service.RefreshAsync(ctx))
endpoints.MapPost<IApiAuthEndpointService, ApiRefreshTokenRequest>(
"api/auth/refresh",
(service, request, ctx) => service.RefreshAsync(request, ctx))
.WithName("ApiRefresh")
.WithOpenApi("Auth", "API refresh token 轮换。", "", typeof(ApiRefreshTokenRequest), typeof(AuthTokenResponse))
.ApiOnly();
endpoints.MapPost<IApiAuthEndpointService>("api/auth/logout", (service, ctx) => service.LogoutAsync(ctx))
endpoints.MapPost<IApiAuthEndpointService, ApiLogoutRequest>(
"api/auth/logout",
(service, request, ctx) => service.LogoutAsync(request, ctx))
.WithName("ApiLogout")
.WithOpenApi("Auth", "API 退出登录并吊销 refresh token。", "", typeof(ApiLogoutRequest))
.ApiOnly();
@@ -41,17 +47,23 @@ namespace Avalonia_Services.Endpoints
{
builder.ConfigureEndpoints(endpoints =>
{
endpoints.MapPost<IPcAuthEndpointService>("api/pc/auth/authorize", (service, ctx) => service.AuthorizeAsync(ctx))
endpoints.MapPost<IPcAuthEndpointService, PcAuthorizeRequest>(
"api/pc/auth/authorize",
(service, request, ctx) => service.AuthorizeAsync(request, ctx))
.WithName("PcAuthorize")
.WithOpenApi("Auth", "PC 授权码登录，生成本地全局 token。", "", typeof(PcAuthorizeRequest), typeof(PcTokenResponse))
.PcOnly();
endpoints.MapPost<IPcAuthEndpointService>("api/pc/auth/refresh", (service, ctx) => service.RefreshAsync(ctx))
endpoints.MapPost<IPcAuthEndpointService, PcRefreshRequest>(
"api/pc/auth/refresh",
(service, request, ctx) => service.RefreshAsync(request, ctx))
.WithName("PcRefresh")
.WithOpenApi("Auth", "PC 全局 token 刷新。", "", typeof(PcRefreshRequest), typeof(PcTokenResponse))
.PcOnly();
endpoints.MapPost<IPcAuthEndpointService>("api/pc/auth/logout", (service, ctx) => service.LogoutAsync(ctx))
endpoints.MapPost<IPcAuthEndpointService, PcLogoutRequest>(
"api/pc/auth/logout",
(service, request, ctx) => service.LogoutAsync(request, ctx))
.WithName("PcLogout")
.WithOpenApi("Auth", "PC 退出登录。", "", typeof(PcLogoutRequest))
.PcOnly();
Avalonia-Services/Extensions/DesktopEndpointAdapter.cs
+14 -4
View File
@@ -109,10 +109,19 @@ namespace Avalonia_Services.Extensions
Dictionary<string, string>? query = null)
{
// 查找匹配的端点（忽略大小写 + 方法匹配）
var endpoint = _endpoints.Endpoints.FirstOrDefault(e =>
e.SupportsHost(EndpointHostTarget.Pc) &&
string.Equals(e.Pattern, path, StringComparison.OrdinalIgnoreCase) &&
string.Equals(e.HttpMethod, method, StringComparison.OrdinalIgnoreCase));
var match = _endpoints.Endpoints
.Where(e =>
e.SupportsHost(EndpointHostTarget.Pc) &&
string.Equals(e.HttpMethod, method, StringComparison.OrdinalIgnoreCase))
.Select(e => new
{
Endpoint = e,
IsMatched = ServiceEndpointPatternMatcher.TryMatch(e.Pattern, path, out var routeValues),
RouteValues = routeValues,
})
.FirstOrDefault(candidate => candidate.IsMatched);
var endpoint = match?.Endpoint;
if (endpoint is null)
{
@@ -127,6 +136,7 @@ namespace Avalonia_Services.Extensions
Body = body,
Headers = headers ?? new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase),
Query = query ?? new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase),
RouteValues = match!.RouteValues,
Items = { ["ServiceProvider"] = _serviceProvider },
};
Avalonia-Services/Services/AuthService/AuthEndpointServices.cs
+7 -6
View File
@@ -1,3 +1,4 @@
using Avalonia_Common.Core;
using Avalonia_Services.Core;
using System.Threading.Tasks;
@@ -13,21 +14,21 @@ namespace Avalonia_Services.Services.AuthService
/// </summary>
/// <param name="ctx">服务端点上下文。</param>
/// <returns>包含 Token 的认证响应。</returns>
Task<object?> LoginAsync(ServiceEndpointContext ctx);
Task<IApiResponse> LoginAsync(ApiLoginRequest request, ServiceEndpointContext ctx);
/// <summary>
/// 使用 Refresh Token 刷新 Access Token。
/// </summary>
/// <param name="ctx">服务端点上下文。</param>
/// <returns>新的 Token 对。</returns>
Task<object?> RefreshAsync(ServiceEndpointContext ctx);
Task<IApiResponse> RefreshAsync(ApiRefreshTokenRequest request, ServiceEndpointContext ctx);
/// <summary>
/// 处理用户登出请求。
/// </summary>
/// <param name="ctx">服务端点上下文。</param>
/// <returns>登出结果。</returns>
Task<object?> LogoutAsync(ServiceEndpointContext ctx);
Task<IApiResponse> LogoutAsync(ApiLogoutRequest request, ServiceEndpointContext ctx);
}
/// <summary>
@@ -40,20 +41,20 @@ namespace Avalonia_Services.Services.AuthService
/// </summary>
/// <param name="ctx">服务端点上下文。</param>
/// <returns>包含 Token 的认证响应。</returns>
Task<object?> AuthorizeAsync(ServiceEndpointContext ctx);
Task<IApiResponse> AuthorizeAsync(PcAuthorizeRequest request, ServiceEndpointContext ctx);
/// <summary>
/// 刷新当前 Token。
/// </summary>
/// <param name="ctx">服务端点上下文。</param>
/// <returns>新的 Token 响应。</returns>
Task<object?> RefreshAsync(ServiceEndpointContext ctx);
Task<IApiResponse> RefreshAsync(PcRefreshRequest request, ServiceEndpointContext ctx);
/// <summary>
/// 处理用户登出请求。
/// </summary>
/// <param name="ctx">服务端点上下文。</param>
/// <returns>登出结果。</returns>
Task<object?> LogoutAsync(ServiceEndpointContext ctx);
Task<IApiResponse> LogoutAsync(PcLogoutRequest request, ServiceEndpointContext ctx);
}
}