feat: 二维码访问功能，统一端点管道增强，端点迁移至 Services 层

- 新增二维码生成端点，自动检测局域网 IP，前端扫一扫即可打开网站 - 提取 IApiResponse 接口，ServiceRequestBinder 支持强类型请求 DTO 绑定 - FileStream 端点迁移至 AppEndpoints 统一注册，管道支持 FileStreamResponse 原始文件返回 - 文件库端点全面使用 MapGet<TService, TRequest> 泛型注册 - 移除 Avalonia-API/Extensions 中的业务端点文件，统一由 Services 层管理
2026-05-22 11:18:47 +08:00
parent a16c32b25e
commit d84bbb3a18
35 changed files with 888 additions and 284 deletions
@@ -17,6 +17,19 @@ namespace Avalonia_Services.Services.FileLibrary
    public sealed record DeleteLibraryRootRequest(
        [property: JsonPropertyName("id")] int Id);

+    public sealed record DirectoryQueryRequest(
+        [property: JsonPropertyName("path")] string? Path);
+
+    public sealed record FileQueryRequest(
+        [property: JsonPropertyName("id")] int Id);
+
+    public sealed record SearchFilesRequest(
+        [property: JsonPropertyName("page")] int Page = 1,
+        [property: JsonPropertyName("pageSize")] int PageSize = 24,
+        [property: JsonPropertyName("mediaType")] string? MediaType = null,
+        [property: JsonPropertyName("keyword")] string? Keyword = null,
+        [property: JsonPropertyName("rootId")] int RootId = 0);
+
    public sealed record DriveDto(
        string Name,
        string DisplayName,
@@ -1,99 +1,77 @@
 using Avalonia_Common.Core;
 using Avalonia_Services.Core;
-using System.Text.Json;

 namespace Avalonia_Services.Services.FileLibrary
 {
    public sealed class FileLibraryEndpointService(IFileLibraryService fileLibrary) : IFileLibraryEndpointService
    {
-        private static readonly JsonSerializerOptions JsonOptions = new()
-        {
-            PropertyNameCaseInsensitive = true,
-        };
-
-        public async Task<object?> GetDrivesAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> GetDrivesAsync(ServiceEndpointContext ctx)
        {
            return ResponseHelper.Ok(await fileLibrary.GetDrivesAsync());
        }

-        public async Task<object?> GetDirectoriesAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> GetDirectoriesAsync(DirectoryQueryRequest request)
        {
-            var path = ctx.Query.GetValueOrDefault("path");
-            return ResponseHelper.Ok(await fileLibrary.GetDirectoriesAsync(path));
+            return ResponseHelper.Ok(await fileLibrary.GetDirectoriesAsync(request.Path));
        }

-        public async Task<object?> GetRootsAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> GetRootsAsync(ServiceEndpointContext ctx)
        {
            return ResponseHelper.Ok(await fileLibrary.GetRootsAsync());
        }

-        public async Task<object?> AddRootAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> AddRootAsync(AddLibraryRootRequest request)
        {
-            var request = ReadBody<AddLibraryRootRequest>(ctx);
            return ResponseHelper.Ok(await fileLibrary.AddRootAsync(request), "文件库目录已添加并完成扫描。");
        }

-        public async Task<object?> SetRootEnabledAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> SetRootEnabledAsync(UpdateLibraryRootRequest request)
        {
-            var request = ReadBody<UpdateLibraryRootRequest>(ctx);
            return ResponseHelper.Ok(await fileLibrary.SetRootEnabledAsync(request), "文件库目录状态已更新。");
        }

-        public async Task<object?> DeleteRootAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> DeleteRootAsync(DeleteLibraryRootRequest request)
        {
-            var request = ReadBody<DeleteLibraryRootRequest>(ctx);
            await fileLibrary.DeleteRootAsync(request);
            return ResponseHelper.Succeed("文件库目录已删除。");
        }

-        public async Task<object?> ScanRootAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> ScanRootAsync(ScanLibraryRootRequest request)
        {
-            var request = ReadBody<ScanLibraryRootRequest>(ctx);
            return ResponseHelper.Ok(await fileLibrary.ScanRootAsync(request.Id), "文件库目录扫描完成。");
        }

-        public async Task<object?> SearchFilesAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> SearchFilesAsync(SearchFilesRequest request)
        {
-            return await fileLibrary.SearchFilesAsync(ctx);
+            return await fileLibrary.SearchFilesAsync(request);
        }

-        public async Task<object?> GetFileAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> GetFileAsync(FileQueryRequest request)
        {
-            var id = ReadId(ctx);
-            var file = await fileLibrary.GetFileAsync(id);
+            ValidateFileId(request.Id);
+            var file = await fileLibrary.GetFileAsync(request.Id);
            return file is null
                ? ResponseHelper.Failure(404, "文件不存在或尚未扫描入库。")
                : ResponseHelper.Ok(file);
        }

-        public async Task<object?> GetTextPreviewAsync(ServiceEndpointContext ctx)
+        public async Task<IApiResponse> GetTextPreviewAsync(FileQueryRequest request)
        {
-            var id = ReadId(ctx);
-            var preview = await fileLibrary.GetTextPreviewAsync(id);
+            ValidateFileId(request.Id);
+            var preview = await fileLibrary.GetTextPreviewAsync(request.Id);
            return preview is null
                ? ResponseHelper.Failure(404, "文本文件不存在或无法预览。")
                : ResponseHelper.Ok(preview);
        }

-        private static T ReadBody<T>(ServiceEndpointContext ctx)
+        private static void ValidateFileId(int id)
        {
-            if (string.IsNullOrWhiteSpace(ctx.Body))
+            if (id > 0)
            {
-                throw new InvalidOperationException("请求体不能为空。");
+                return;
            }

-            var body = JsonSerializer.Deserialize<T>(ctx.Body, JsonOptions);
-            return body ?? throw new InvalidOperationException("请求体格式错误。");
-        }
-
-        private static int ReadId(ServiceEndpointContext ctx)
-        {
-            if (int.TryParse(ctx.Query.GetValueOrDefault("id"), out var id) && id > 0)
-            {
-                return id;
-            }
-
-            throw new InvalidOperationException("id 参数无效。");
+            throw new ArgumentException("id 参数无效。");
        }
    }
 }
@@ -213,13 +213,13 @@ namespace Avalonia_Services.Services.FileLibrary
            }
        }

-        public async Task<PagedResponse<FileRecordDto>> SearchFilesAsync(ServiceEndpointContext ctx, CancellationToken cancellationToken = default)
+        public async Task<PagedResponse<FileRecordDto>> SearchFilesAsync(SearchFilesRequest request, CancellationToken cancellationToken = default)
        {
-            var page = ParseInt(ctx.Query.GetValueOrDefault("page"), 1, 1, 100000);
-            var pageSize = ParseInt(ctx.Query.GetValueOrDefault("pageSize"), 24, 1, 100);
-            var mediaType = ctx.Query.GetValueOrDefault("mediaType")?.Trim();
-            var keyword = ctx.Query.GetValueOrDefault("keyword")?.Trim();
-            var rootId = ParseInt(ctx.Query.GetValueOrDefault("rootId"), 0, 0, int.MaxValue);
+            var page = Math.Clamp(request.Page, 1, 100000);
+            var pageSize = Math.Clamp(request.PageSize, 1, 100);
+            var mediaType = request.MediaType?.Trim();
+            var keyword = request.Keyword?.Trim();
+            var rootId = Math.Clamp(request.RootId, 0, int.MaxValue);

            var query = db.ManagedFileRecords
                .AsNoTracking()
@@ -399,11 +399,5 @@ namespace Avalonia_Services.Services.FileLibrary
                MediaFileTypes.IsBrowserPlayable(file.Extension));
        }

-        private static int ParseInt(string? value, int fallback, int min, int max)
-        {
-            return int.TryParse(value, out var parsed)
-                ? Math.Clamp(parsed, min, max)
-                : fallback;
-        }
    }
 }
@@ -0,0 +1,37 @@
+using Avalonia_EFCore.Database;
+using Avalonia_EFCore.Models;
+using Avalonia_Services.Core;
+using Microsoft.EntityFrameworkCore;
+
+namespace Avalonia_Services.Services.FileLibrary
+{
+    public interface IFileStreamService
+    {
+        Task<FileStreamResponse?> GetFileStreamAsync(int id, CancellationToken cancellationToken = default);
+    }
+
+    public sealed class FileStreamService(AppDataContext db) : IFileStreamService
+    {
+        public async Task<FileStreamResponse?> GetFileStreamAsync(int id, CancellationToken cancellationToken = default)
+        {
+            var file = await db.ManagedFileRecords
+                .AsNoTracking()
+                .Include(item => item.LibraryRoot)
+                .FirstOrDefaultAsync(item =>
+                    item.Id == id
+                    && item.Exists
+                    && item.LibraryRoot != null
+                    && item.LibraryRoot.IsAvailable,
+                    cancellationToken);
+
+            if (file is null || !System.IO.File.Exists(file.AbsolutePath))
+                return null;
+
+            return new FileStreamResponse(
+                file.AbsolutePath,
+                file.FileName,
+                file.ContentType,
+                file.LastWriteTimeUtc);
+        }
+    }
+}
@@ -1,27 +1,28 @@
+using Avalonia_Common.Core;
 using Avalonia_Services.Core;

 namespace Avalonia_Services.Services.FileLibrary
 {
    public interface IFileLibraryEndpointService
    {
-        Task<object?> GetDrivesAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> GetDrivesAsync(ServiceEndpointContext ctx);

-        Task<object?> GetDirectoriesAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> GetDirectoriesAsync(DirectoryQueryRequest request);

-        Task<object?> GetRootsAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> GetRootsAsync(ServiceEndpointContext ctx);

-        Task<object?> AddRootAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> AddRootAsync(AddLibraryRootRequest request);

-        Task<object?> SetRootEnabledAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> SetRootEnabledAsync(UpdateLibraryRootRequest request);

-        Task<object?> DeleteRootAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> DeleteRootAsync(DeleteLibraryRootRequest request);

-        Task<object?> ScanRootAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> ScanRootAsync(ScanLibraryRootRequest request);

-        Task<object?> SearchFilesAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> SearchFilesAsync(SearchFilesRequest request);

-        Task<object?> GetFileAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> GetFileAsync(FileQueryRequest request);

-        Task<object?> GetTextPreviewAsync(ServiceEndpointContext ctx);
+        Task<IApiResponse> GetTextPreviewAsync(FileQueryRequest request);
    }
 }
@@ -1,5 +1,4 @@
 using Avalonia_Common.Core;
-using Avalonia_Services.Core;

 namespace Avalonia_Services.Services.FileLibrary
 {
@@ -21,7 +20,7 @@ namespace Avalonia_Services.Services.FileLibrary

        Task ScanDueRootsAsync(CancellationToken cancellationToken = default);

-        Task<PagedResponse<FileRecordDto>> SearchFilesAsync(ServiceEndpointContext ctx, CancellationToken cancellationToken = default);
+        Task<PagedResponse<FileRecordDto>> SearchFilesAsync(SearchFilesRequest request, CancellationToken cancellationToken = default);

        Task<FileRecordDto?> GetFileAsync(int id, CancellationToken cancellationToken = default);