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

- 新增 IApiResponse 统一响应契约，覆盖普通响应和分页响应 - 扩展端点映射，支持 IApiResponse 和带请求 DTO 的 MapXxx 重载 - 增加 Body、Query、Route Values 到请求 DTO 的自动绑定 - 增加 PC 端路由模式匹配，支持 {id} 和 {id:int} - API 与 PC 端点上下文补充路由参数传递 - 调整 OpenAPI 请求类型处理，避免 GET/DELETE 被标记为 JSON Body - 鉴权端点迁移到强类型请求绑定和 IApiResponse 返回 - 增加统一端点文件流响应支持
2026-05-22 11:42:38 +08:00
parent e72bff954b
commit 5cdc7052e0
13 changed files with 414 additions and 82 deletions
@@ -0,0 +1,11 @@
+namespace Avalonia_Services.Core
+{
+    /// <summary>
+    /// 文件流响应 —— 管道检测到此类型时将返回原始文件而非 JSON。
+    /// </summary>
+    public sealed record FileStreamResponse(
+        string FilePath,
+        string FileName,
+        string ContentType,
+        DateTime LastModified);
+}
@@ -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>
@@ -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>
@@ -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 _);
+        }
+    }
+}
@@ -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);
+            }
+        }
+    }
+}