尧图网站建设 
Oqtane 模块开发实践指南基于 awesome-copilot 的 Blazor 模块分层模式与代码规范【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本文面向正在使用 Oqtane 框架开发模块的 .NET/Blazor 开发者。以 awesome-copilot 仓库中 instructions/oqtane.instructions.md 为骨架系统讲解 Oqtane 模块的标准代码风格、命名约定、客户端/服务端分层模式ModuleBase / ServiceBase / MVC Controller / Repository、缓存与状态管理策略、测试调试与安全实践并说明如何将该指令接入工作区让 GitHub Copilot 遵循这些规范。读完本文你将掌握一套可直接落地到 Oqtane 模块项目中的工程化开发范式。指令定位这份 Oqtane 指令文件解决什么问题在 awesome-copilot 仓库中instructions/目录存放了一批团队与项目级自定义指令用于增强 GitHub Copilot 对特定技术栈的行为。其中的 instructions/oqtane.instructions.md 正是一份面向Oqtane 模块开发的指令文件其 frontmatter 明确声明了适用范围description: Oqtane Module patterns applyTo: **/*.razor, **/*.razor.cs, **/*.razor.cssapplyTo字段意味着当 Copilot 在处理工作区内的 Razor 组件.razor、组件代码隐藏文件.razor.cs与组件样式文件.razor.css时这份指令会被自动加载并约束其输出。因此它的本质是一套让 AI 助手按 Oqtane 官方模块模式写代码的约束集与仓库内同类的 instructions/blazor.instructions.mdBlazor 通用组件模式和 instructions/csharp.instructions.mdC# 通用开发规范互为补充前者讲 Oqtane 特化架构后两者提供 Blazor 与 C# 的通用底座。一、Blazor 代码风格与结构写出符合 Oqtane 预期的组件指令首先强调了代码风格与结构层面的总原则这些是 Oqtane 模块代码审查的第一道门槛编写惯用的、高效的 Blazor 与 C# 代码遵循 .NET 与 Blazor 的既有约定避免看起来能跑但与生态格格不入的写法。合理使用 Razor 组件组件化 UI 开发是 Blazor 的核心形态Oqtane 的每个模块动作都是一个独立 Razor 文件详见后文 Oqtane 分层模式因此组件边界的清晰与否直接决定模块可维护性。小组件优先内联函数复杂逻辑下沉对于几十行的简单组件把事件处理逻辑直接内联即可一旦逻辑变复杂应立即将其抽取到 code-behind.razor.cs或独立的服务类中保持组件文件的声明式纯粹。异步优先async/await应用于所有可能阻塞 UI 的操作确保 Blazor 交互链路非阻塞。这一点在 Blazor Server 模式下尤其关键——过长的同步操作会直接阻塞 SignalR 渲染循环。从结构上看这部分与 instructions/blazor.instructions.md 的开篇完全一致说明 Oqtane 指令是在 Blazor 通用规范之上叠加了框架特有的约束二者应配套使用。二、命名约定让模块代码可被团队与工具一致解读指令给出的命名约定是 .NET 生态的标准做法但作为显式约束写进 Copilot 指令是为了防止 AI 生成风格漂移的标识符类别规则示例组件名、方法名、公共成员PascalCaseProductList,LoadProductsAsync私有字段、局部变量camelCase_productService,items接口以I前缀IUserService其中私有字段使用camelCase在 Oqtane 社区中通常配合下划线前缀如_repository使用这与 instructions/csharp.instructions.md 中遵循.editorconfig中定义的代码格式化风格的建议一致——建议在仓库根放置.editorconfig固化这些规则。三、Blazor 与 .NET 特有规范生命周期、绑定、DI 与语言特性3.1 生命周期方法指令要求充分利用 Blazor 内置的生命周期钩子尤其是异步版本OnInitializedAsync组件首次初始化时获取数据、解析服务依赖是模块中进入页面即加载列表/详情的标准入口。OnParametersSetAsync当父组件传入参数如模块的ModuleId、PageId变化时重新加载数据适用于 Oqtane 模块间导航切换场景。一个典型的 Oqtane 列表页生命周期写法protected override async Task OnInitializedAsync() { await base.OnInitializedAsync(); Items await Service.GetItemsAsync(ModuleState.ModuleId); }3.2 数据绑定与 DI使用bind实现双向数据绑定例如bind-Value绑定表单字段、bind-SelectedValue绑定下拉选择。所有服务通过依赖注入获取Oqtane 的 DI 容器会注入模块服务、Repository 以及框架级服务如INavigationManager、ISiteState。组件内不要手动new服务否则会破坏单例/作用域生命周期并让单元测试变得困难。组件与服务之间遵循关注点分离Separation of ConcernsUI 表现、业务编排、数据访问分属不同层这也是下文 Oqtane 分层模式的理论基础。3.3 C# 语言版本指令明确要求始终使用最新版本的 C#当前为 C# 13 特性包括record 类型用于不可变数据传输对象DTO模块中客户端与服务端交换的数据模型非常适合。模式匹配switch表达式、属性模式、列表模式等简化条件分支。全局 using将常用的using Oqtane.Modules;、using Oqtane.Services;等集中到GlobalUsings.cs减少每个文件头部的重复引用。需要说明的是仓库内的 instructions/csharp.instructions.md 已更新为C# 14 特性而本 Oqtane 指令仍记录为 C# 13。实际开发时应以本地global.json与 SDK 版本为准二者指向的语言特性集合record、模式匹配、全局 using完全兼容不影响落地。四、Oqtane 特有指南模块分层的核心骨架这是整份指令文件的技术灵魂所在。Oqtane 的模块采用典型的客户端/服务端client/server分离模式指令用五条规则勾勒出了完整的请求链路4.1 总体模式一条请求的五层链路Razor 组件ModuleBase 派生 │ 调用 ▼ Client 服务类ServiceBase 派生services 文件夹 │ ServiceBase 方法GetAsync/PostAsync 等 ▼ Server MVC Controller每个模块一个匹配客户端调用 │ DI 注入 ▼ Server 服务/Repository每个模块一个数据访问 ▼ 数据库4.2 客户端一个动作一个 Razor 文件Client 项目中modules文件夹下存放各个模块每个模块目录内每一个动作action都是一个独立的 Razor 文件且必须继承自ModuleBase其中index.razor是模块的默认动作默认视图。这意味着一个模块通常拥有index.razor默认列表/主页、add.razor新增、edit.razor编辑等若干组件各自对应一个动作URL 路由与动作一一对应。4.3 客户端复杂处理下沉到 ServiceBase 服务对于需要获取数据等复杂客户端处理创建一个继承自ServiceBase的服务类放在services文件夹中一个模块对应一个服务类也可拆分为接口 实现如IProductService/ProductService符合指令中接口加I前缀的约定。客户端服务通过ServiceBase提供的方法调用服务端端点。ServiceBase封装了 Oqtane 的 HTTP 客户端基础设施路由拼接、认证令牌、JSON 序列化、错误处理因此模块代码中不应直接裸用HttpClient而应复用基类能力。一个典型的服务类骨架public class ProductService : ServiceBase, IProductService { private readonly SiteState _siteState; public ProductService(HttpClient http, SiteState siteState) : base(http) { _siteState siteState; } public async TaskListProduct GetProductsAsync(int moduleId) { return await GetJsonAsyncListProduct( ${ApiRoute}{_siteState.Alias.Path}api/Product/Get?moduleId{moduleId}); } public async TaskProduct GetProductAsync(int moduleId, int productId) { return await GetJsonAsyncProduct( ${ApiRoute}{_siteState.Alias.Path}api/Product/Get?moduleId{moduleId}productId{productId}); } }其中ApiRoute由ServiceBase提供GetJsonAsync/PostJsonAsync等ServiceBase方法封装了标准的 Oqtane API 调用约定。4.4 服务端MVC Controller 与 Repository 一一对应Server 项目包含MVC Controller每个模块一个且 Controller 的动作签名要与客户端服务调用严格匹配包括路由模板与参数名Oqtane 中 Controller 与 Service 的命名也通常一一对应如ProductController对应IProductService。每个 Controller 通过DI 注入服务端服务或 Repository自身不直接写 SQL。Server 项目使用Repository 模式一个模块一个 Repository 类与 Controller 对应负责数据访问通常基于 EF Core 的DBContext。Repository 内部实现 CRUD 与查询Controller 负责参数校验、权限判定与结果返回。[Route({alias}/api/[controller])] public class ProductController : Controller { private readonly IProductRepository _repository; public ProductController(IProductRepository repository) { _repository repository; } [HttpGet] public async TaskIActionResult Get(int moduleId, int? productId) { if (productId.HasValue) { var product await _repository.GetProductAsync(productId.Value); return Ok(product); } return Ok(await _repository.GetProductsAsync(moduleId)); } }4.5 为什么必须遵循这套分层这套模式的工程收益非常明确客户端组件只关心展示与交互客户端服务只关心API 调用契约Controller 只关心HTTP 协议适配Repository 只关心数据访问。任何一层都可以独立替换与测试——这也为后文的单元测试、依赖 Mock 提供了清晰的边界。指令建议开发者参考官方 Oqtane 框架仓库中的基类ModuleBase、ServiceBase等与既有模块实现来对齐最新模式。五、错误处理与验证让模块稳定可观测为 Blazor 页面与 API 调用实现完善的错误处理UI 层捕获异常并给出用户可读的反馈而不是让未处理异常直达渲染循环。使用基类内置的 Oqtane 日志方法ModuleBase等基类自带Logger实例优先使用它们做后端错误跟踪与 Oqtane 的日志体系写入站点日志表对齐而不是另起一套。UI 层错误隔离在 Blazor 中使用ErrorBoundary捕获组件树渲染期间的异常避免整页白屏ErrorBoundary ChildContent ProductList / /ChildContent ErrorContent div classalert alert-danger数据加载失败请稍后重试。/div /ErrorContent /ErrorBoundary表单验证使用FluentValidation 或 DataAnnotations实现表单校验。Oqtane 的实体模型如IEntity派生类可标注[Required]、[StringLength]等特性配合 Blazor 的EditFormDataAnnotationsValidator即可获得开箱即用的校验体验。六、Blazor API 调用与性能优化按需选择托管模式根据项目需求在 Blazor Server 与 Blazor WebAssembly 之间做出权衡。Oqtane 支持两种模式Server 模式交互低延迟、便于服务端安全控制WebAssembly 模式可将计算与状态卸载到浏览器端。异步调用所有 API 调用与可能阻塞主线程的 UI 操作都使用async/await配合ServiceBase的异步方法天然满足该要求。减少不必要的渲染用StateHasChanged()精准触发重绘而不是在无关场景下随手调用用ShouldRender()在数据未变化时跳过渲染降低组件树重建成本protected override bool ShouldRender() { return _dataChanged || base.ShouldRender(); }EventCallback 传递最小数据子组件向父组件通知事件时使用EventCallbackT并只传必要参数如仅传int类型的 ID而非整个实体对象减少序列化与依赖传递。七、缓存策略按托管模式分层选型指令给出的缓存策略按部署形态分层具有很强的针对性场景推荐方案说明Blazor Server 频繁读取的数据IMemoryCache轻量级进程内缓存适合站点配置、权限字典等变化不频繁的数据Blazor WebAssembly 会话间状态localStorage/sessionStorage浏览器端持久化避免刷新丢状态多用户共享状态的大型应用分布式缓存Redis / SQL Server Cache跨实例共享状态支持横向扩展API 响应缓存接口返回对不易变化的数据避免重复请求改善用户体验在 Oqtane 模块中IMemoryCache可以直接通过 DI 注入使用WebAssembly 场景则可借助Blazored.LocalStorage/Blazored.SessionStorage实现详见下一节。八、状态管理内置优先克制引入三方库指令在状态管理上的态度非常务实——优先使用框架内置能力仅在必要时引入额外依赖基础状态共享使用 Blazor 内置的Cascading Parameters与EventCallbacks在组件间传递状态。Oqtane 内置状态直接使用 Oqtane 基类提供的PageState与SiteState。SiteState携带当前站点别名、用户信息等是模块中最常用的框架级状态客户端服务构建 API 路由时也依赖它见 4.3 示例。避免过度依赖指令明确提示——当应用复杂度上升时不要轻易引入 Fluxor 或 BlazorState 之类的状态库因为 Oqtane 自身的页面/模块模型已承担了大部分状态职责额外引入只会增加学习与调试成本。WebAssembly 端持久化如确需在页面刷新后保持状态使用Blazored.LocalStorage或Blazored.SessionStorage。Server 端会话状态使用Scoped 服务 StateContainer 模式管理用户会话内状态同时最小化重渲染public class ProductStateContainer { public ListProduct CurrentItems { get; private set; } new(); public event Action? OnChange; public void SetItems(ListProduct items) { CurrentItems items; OnChange?.Invoke(); } }九、API 设计与集成客户端与服务端的通信统一走ServiceBase方法无论目标是 Oqtane 服务端后端还是外部 API都经由服务类中转保持调用方与传输细节解耦。每个 API 调用都应有try-catch 错误处理并向 UI 提供恰当的反馈错误提示、降级展示、重试入口避免异常静默或直接冒泡。十、测试与调试Visual Studio 下的质量保障指令对测试与调试给出了明确要求单元测试与集成测试在 Visual Studio Enterprise 中执行这是该指令设定的团队约束注意仓库内 instructions/blazor.instructions.md 采用更开放的跨 IDE 主张具体以团队规范为准。测试框架使用xUnit、NUnit 或 MSTest测试 Blazor 组件与服务。依赖 Mock使用Moq 或 NSubstitute模拟依赖。结合前文的分层架构可以非常干净地测试各层——例如 MockIProductRepository来单测 ControllerMock 客户端IProductService来测组件交互[Fact] public async Task Get_Returns_Products_From_Repository() { var repo new MockIProductRepository(); repo.Setup(r r.GetProductsAsync(It.IsAnyint())) .ReturnsAsync(new ListProduct { new Product { Name Demo } }); var controller new ProductController(repo.Object); var result await controller.Get(1, null) as OkObjectResult; Assert.NotNull(result); Assert.IsTypeListProduct(result.Value); }调试策略前端 Blazor UI 问题使用浏览器开发者工具网络面板、控制台后端与服务端问题使用Visual Studio 调试工具断点、调用堆栈、即时窗口。性能剖析依赖Visual Studio 的诊断工具CPU 使用率、内存分配定位渲染与数据访问热点。十一、安全与认证利用 Oqtane 内置成员认证与授权优先使用 Oqtane 基类内置成员最典型的是User.Rolesprotected override async Task OnInitializedAsync() { if (!User.IsInRole(Constants.RoleNames.Admin)) { NavigationManager.NavigateTo(Unauthorized); return; } await base.OnInitializedAsync(); }Oqtane 的权限模型基于角色与权限字符串如View、Edit、AdminModuleBase提供的User属性封装了当前用户的认证状态模块动作级授权应基于这些内置成员实现而非自行发明一套会话体系。通信安全所有 Web 通信使用HTTPS并为跨源访问配置合理的CORS 策略防止敏感接口被未授权域调用。十二、如何将该指令接入你的 Oqtane 工作区按照 docs/README.instructions.md 的说明自定义指令有两种落地方式复制到.github/copilot-instructions.md作为全局项目指令对整个仓库生效放入.github/instructions/目录创建任务级指令文件例如.github/instructions/my-oqtane-rules.instructions.md将本文讲解的规范内容放入其中。也可以直接在 VS Code / VS Code Insiders 中一键安装本仓库的 Oqtane 指令通过 docs/README.instructions.md 表格中的 Install 按钮。一旦安装进工作区指令即自动作用于 Copilot 对**/*.razor、**/*.razor.cs、**/*.razor.css文件的生成与修改后续所有新增模块代码都将遵循本文梳理的分层模式、命名约定与工程实践。总结instructions/oqtane.instructions.md 虽然篇幅精炼却完整覆盖了 Oqtane 模块开发的全部关键维度从 Blazor 代码风格、命名约定与语言特性到ModuleBase/ServiceBase/MVC Controller/Repository 四层链路的分层模式再到错误处理、性能优化、缓存、状态管理、测试调试与安全认证。它的价值在于把这些老手才知道的约定固化为 Copilot 的显式行为约束。在实际项目中建议将它与 instructions/blazor.instructions.mdBlazor 通用规范和 instructions/csharp.instructions.mdC# 基础规范配套启用形成Oqtane 特化 Blazor 通用 C# 底座的完整 AI 编码约束体系从而让 Copilot 产出的模块代码从一开始就符合 Oqtane 的架构预期。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Oqtane 模块开发实践指南：基于 awesome-copilot 的 Blazor 模块分层模式与代码规范
Oqtane 模块开发实践指南基于 awesome-copilot 的 Blazor 模块分层模式与代码规范【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot本文面向正在使用 Oqtane 框架开发模块的 .NET/Blazor 开发者。以 awesome-copilot 仓库中 instructions/oqtane.instructions.md 为骨架系统讲解 Oqtane 模块的标准代码风格、命名约定、客户端/服务端分层模式ModuleBase / ServiceBase / MVC Controller / Repository、缓存与状态管理策略、测试调试与安全实践并说明如何将该指令接入工作区让 GitHub Copilot 遵循这些规范。读完本文你将掌握一套可直接落地到 Oqtane 模块项目中的工程化开发范式。指令定位这份 Oqtane 指令文件解决什么问题在 awesome-copilot 仓库中instructions/目录存放了一批团队与项目级自定义指令用于增强 GitHub Copilot 对特定技术栈的行为。其中的 instructions/oqtane.instructions.md 正是一份面向Oqtane 模块开发的指令文件其 frontmatter 明确声明了适用范围description: Oqtane Module patterns applyTo: **/*.razor, **/*.razor.cs, **/*.razor.cssapplyTo字段意味着当 Copilot 在处理工作区内的 Razor 组件.razor、组件代码隐藏文件.razor.cs与组件样式文件.razor.css时这份指令会被自动加载并约束其输出。因此它的本质是一套让 AI 助手按 Oqtane 官方模块模式写代码的约束集与仓库内同类的 instructions/blazor.instructions.mdBlazor 通用组件模式和 instructions/csharp.instructions.mdC# 通用开发规范互为补充前者讲 Oqtane 特化架构后两者提供 Blazor 与 C# 的通用底座。一、Blazor 代码风格与结构写出符合 Oqtane 预期的组件指令首先强调了代码风格与结构层面的总原则这些是 Oqtane 模块代码审查的第一道门槛编写惯用的、高效的 Blazor 与 C# 代码遵循 .NET 与 Blazor 的既有约定避免看起来能跑但与生态格格不入的写法。合理使用 Razor 组件组件化 UI 开发是 Blazor 的核心形态Oqtane 的每个模块动作都是一个独立 Razor 文件详见后文 Oqtane 分层模式因此组件边界的清晰与否直接决定模块可维护性。小组件优先内联函数复杂逻辑下沉对于几十行的简单组件把事件处理逻辑直接内联即可一旦逻辑变复杂应立即将其抽取到 code-behind.razor.cs或独立的服务类中保持组件文件的声明式纯粹。异步优先async/await应用于所有可能阻塞 UI 的操作确保 Blazor 交互链路非阻塞。这一点在 Blazor Server 模式下尤其关键——过长的同步操作会直接阻塞 SignalR 渲染循环。从结构上看这部分与 instructions/blazor.instructions.md 的开篇完全一致说明 Oqtane 指令是在 Blazor 通用规范之上叠加了框架特有的约束二者应配套使用。二、命名约定让模块代码可被团队与工具一致解读指令给出的命名约定是 .NET 生态的标准做法但作为显式约束写进 Copilot 指令是为了防止 AI 生成风格漂移的标识符类别规则示例组件名、方法名、公共成员PascalCaseProductList,LoadProductsAsync私有字段、局部变量camelCase_productService,items接口以I前缀IUserService其中私有字段使用camelCase在 Oqtane 社区中通常配合下划线前缀如_repository使用这与 instructions/csharp.instructions.md 中遵循.editorconfig中定义的代码格式化风格的建议一致——建议在仓库根放置.editorconfig固化这些规则。三、Blazor 与 .NET 特有规范生命周期、绑定、DI 与语言特性3.1 生命周期方法指令要求充分利用 Blazor 内置的生命周期钩子尤其是异步版本OnInitializedAsync组件首次初始化时获取数据、解析服务依赖是模块中进入页面即加载列表/详情的标准入口。OnParametersSetAsync当父组件传入参数如模块的ModuleId、PageId变化时重新加载数据适用于 Oqtane 模块间导航切换场景。一个典型的 Oqtane 列表页生命周期写法protected override async Task OnInitializedAsync() { await base.OnInitializedAsync(); Items await Service.GetItemsAsync(ModuleState.ModuleId); }3.2 数据绑定与 DI使用bind实现双向数据绑定例如bind-Value绑定表单字段、bind-SelectedValue绑定下拉选择。所有服务通过依赖注入获取Oqtane 的 DI 容器会注入模块服务、Repository 以及框架级服务如INavigationManager、ISiteState。组件内不要手动new服务否则会破坏单例/作用域生命周期并让单元测试变得困难。组件与服务之间遵循关注点分离Separation of ConcernsUI 表现、业务编排、数据访问分属不同层这也是下文 Oqtane 分层模式的理论基础。3.3 C# 语言版本指令明确要求始终使用最新版本的 C#当前为 C# 13 特性包括record 类型用于不可变数据传输对象DTO模块中客户端与服务端交换的数据模型非常适合。模式匹配switch表达式、属性模式、列表模式等简化条件分支。全局 using将常用的using Oqtane.Modules;、using Oqtane.Services;等集中到GlobalUsings.cs减少每个文件头部的重复引用。需要说明的是仓库内的 instructions/csharp.instructions.md 已更新为C# 14 特性而本 Oqtane 指令仍记录为 C# 13。实际开发时应以本地global.json与 SDK 版本为准二者指向的语言特性集合record、模式匹配、全局 using完全兼容不影响落地。四、Oqtane 特有指南模块分层的核心骨架这是整份指令文件的技术灵魂所在。Oqtane 的模块采用典型的客户端/服务端client/server分离模式指令用五条规则勾勒出了完整的请求链路4.1 总体模式一条请求的五层链路Razor 组件ModuleBase 派生 │ 调用 ▼ Client 服务类ServiceBase 派生services 文件夹 │ ServiceBase 方法GetAsync/PostAsync 等 ▼ Server MVC Controller每个模块一个匹配客户端调用 │ DI 注入 ▼ Server 服务/Repository每个模块一个数据访问 ▼ 数据库4.2 客户端一个动作一个 Razor 文件Client 项目中modules文件夹下存放各个模块每个模块目录内每一个动作action都是一个独立的 Razor 文件且必须继承自ModuleBase其中index.razor是模块的默认动作默认视图。这意味着一个模块通常拥有index.razor默认列表/主页、add.razor新增、edit.razor编辑等若干组件各自对应一个动作URL 路由与动作一一对应。4.3 客户端复杂处理下沉到 ServiceBase 服务对于需要获取数据等复杂客户端处理创建一个继承自ServiceBase的服务类放在services文件夹中一个模块对应一个服务类也可拆分为接口 实现如IProductService/ProductService符合指令中接口加I前缀的约定。客户端服务通过ServiceBase提供的方法调用服务端端点。ServiceBase封装了 Oqtane 的 HTTP 客户端基础设施路由拼接、认证令牌、JSON 序列化、错误处理因此模块代码中不应直接裸用HttpClient而应复用基类能力。一个典型的服务类骨架public class ProductService : ServiceBase, IProductService { private readonly SiteState _siteState; public ProductService(HttpClient http, SiteState siteState) : base(http) { _siteState siteState; } public async TaskListProduct GetProductsAsync(int moduleId) { return await GetJsonAsyncListProduct( ${ApiRoute}{_siteState.Alias.Path}api/Product/Get?moduleId{moduleId}); } public async TaskProduct GetProductAsync(int moduleId, int productId) { return await GetJsonAsyncProduct( ${ApiRoute}{_siteState.Alias.Path}api/Product/Get?moduleId{moduleId}productId{productId}); } }其中ApiRoute由ServiceBase提供GetJsonAsync/PostJsonAsync等ServiceBase方法封装了标准的 Oqtane API 调用约定。4.4 服务端MVC Controller 与 Repository 一一对应Server 项目包含MVC Controller每个模块一个且 Controller 的动作签名要与客户端服务调用严格匹配包括路由模板与参数名Oqtane 中 Controller 与 Service 的命名也通常一一对应如ProductController对应IProductService。每个 Controller 通过DI 注入服务端服务或 Repository自身不直接写 SQL。Server 项目使用Repository 模式一个模块一个 Repository 类与 Controller 对应负责数据访问通常基于 EF Core 的DBContext。Repository 内部实现 CRUD 与查询Controller 负责参数校验、权限判定与结果返回。[Route({alias}/api/[controller])] public class ProductController : Controller { private readonly IProductRepository _repository; public ProductController(IProductRepository repository) { _repository repository; } [HttpGet] public async TaskIActionResult Get(int moduleId, int? productId) { if (productId.HasValue) { var product await _repository.GetProductAsync(productId.Value); return Ok(product); } return Ok(await _repository.GetProductsAsync(moduleId)); } }4.5 为什么必须遵循这套分层这套模式的工程收益非常明确客户端组件只关心展示与交互客户端服务只关心API 调用契约Controller 只关心HTTP 协议适配Repository 只关心数据访问。任何一层都可以独立替换与测试——这也为后文的单元测试、依赖 Mock 提供了清晰的边界。指令建议开发者参考官方 Oqtane 框架仓库中的基类ModuleBase、ServiceBase等与既有模块实现来对齐最新模式。五、错误处理与验证让模块稳定可观测为 Blazor 页面与 API 调用实现完善的错误处理UI 层捕获异常并给出用户可读的反馈而不是让未处理异常直达渲染循环。使用基类内置的 Oqtane 日志方法ModuleBase等基类自带Logger实例优先使用它们做后端错误跟踪与 Oqtane 的日志体系写入站点日志表对齐而不是另起一套。UI 层错误隔离在 Blazor 中使用ErrorBoundary捕获组件树渲染期间的异常避免整页白屏ErrorBoundary ChildContent ProductList / /ChildContent ErrorContent div classalert alert-danger数据加载失败请稍后重试。/div /ErrorContent /ErrorBoundary表单验证使用FluentValidation 或 DataAnnotations实现表单校验。Oqtane 的实体模型如IEntity派生类可标注[Required]、[StringLength]等特性配合 Blazor 的EditFormDataAnnotationsValidator即可获得开箱即用的校验体验。六、Blazor API 调用与性能优化按需选择托管模式根据项目需求在 Blazor Server 与 Blazor WebAssembly 之间做出权衡。Oqtane 支持两种模式Server 模式交互低延迟、便于服务端安全控制WebAssembly 模式可将计算与状态卸载到浏览器端。异步调用所有 API 调用与可能阻塞主线程的 UI 操作都使用async/await配合ServiceBase的异步方法天然满足该要求。减少不必要的渲染用StateHasChanged()精准触发重绘而不是在无关场景下随手调用用ShouldRender()在数据未变化时跳过渲染降低组件树重建成本protected override bool ShouldRender() { return _dataChanged || base.ShouldRender(); }EventCallback 传递最小数据子组件向父组件通知事件时使用EventCallbackT并只传必要参数如仅传int类型的 ID而非整个实体对象减少序列化与依赖传递。七、缓存策略按托管模式分层选型指令给出的缓存策略按部署形态分层具有很强的针对性场景推荐方案说明Blazor Server 频繁读取的数据IMemoryCache轻量级进程内缓存适合站点配置、权限字典等变化不频繁的数据Blazor WebAssembly 会话间状态localStorage/sessionStorage浏览器端持久化避免刷新丢状态多用户共享状态的大型应用分布式缓存Redis / SQL Server Cache跨实例共享状态支持横向扩展API 响应缓存接口返回对不易变化的数据避免重复请求改善用户体验在 Oqtane 模块中IMemoryCache可以直接通过 DI 注入使用WebAssembly 场景则可借助Blazored.LocalStorage/Blazored.SessionStorage实现详见下一节。八、状态管理内置优先克制引入三方库指令在状态管理上的态度非常务实——优先使用框架内置能力仅在必要时引入额外依赖基础状态共享使用 Blazor 内置的Cascading Parameters与EventCallbacks在组件间传递状态。Oqtane 内置状态直接使用 Oqtane 基类提供的PageState与SiteState。SiteState携带当前站点别名、用户信息等是模块中最常用的框架级状态客户端服务构建 API 路由时也依赖它见 4.3 示例。避免过度依赖指令明确提示——当应用复杂度上升时不要轻易引入 Fluxor 或 BlazorState 之类的状态库因为 Oqtane 自身的页面/模块模型已承担了大部分状态职责额外引入只会增加学习与调试成本。WebAssembly 端持久化如确需在页面刷新后保持状态使用Blazored.LocalStorage或Blazored.SessionStorage。Server 端会话状态使用Scoped 服务 StateContainer 模式管理用户会话内状态同时最小化重渲染public class ProductStateContainer { public ListProduct CurrentItems { get; private set; } new(); public event Action? OnChange; public void SetItems(ListProduct items) { CurrentItems items; OnChange?.Invoke(); } }九、API 设计与集成客户端与服务端的通信统一走ServiceBase方法无论目标是 Oqtane 服务端后端还是外部 API都经由服务类中转保持调用方与传输细节解耦。每个 API 调用都应有try-catch 错误处理并向 UI 提供恰当的反馈错误提示、降级展示、重试入口避免异常静默或直接冒泡。十、测试与调试Visual Studio 下的质量保障指令对测试与调试给出了明确要求单元测试与集成测试在 Visual Studio Enterprise 中执行这是该指令设定的团队约束注意仓库内 instructions/blazor.instructions.md 采用更开放的跨 IDE 主张具体以团队规范为准。测试框架使用xUnit、NUnit 或 MSTest测试 Blazor 组件与服务。依赖 Mock使用Moq 或 NSubstitute模拟依赖。结合前文的分层架构可以非常干净地测试各层——例如 MockIProductRepository来单测 ControllerMock 客户端IProductService来测组件交互[Fact] public async Task Get_Returns_Products_From_Repository() { var repo new MockIProductRepository(); repo.Setup(r r.GetProductsAsync(It.IsAnyint())) .ReturnsAsync(new ListProduct { new Product { Name Demo } }); var controller new ProductController(repo.Object); var result await controller.Get(1, null) as OkObjectResult; Assert.NotNull(result); Assert.IsTypeListProduct(result.Value); }调试策略前端 Blazor UI 问题使用浏览器开发者工具网络面板、控制台后端与服务端问题使用Visual Studio 调试工具断点、调用堆栈、即时窗口。性能剖析依赖Visual Studio 的诊断工具CPU 使用率、内存分配定位渲染与数据访问热点。十一、安全与认证利用 Oqtane 内置成员认证与授权优先使用 Oqtane 基类内置成员最典型的是User.Rolesprotected override async Task OnInitializedAsync() { if (!User.IsInRole(Constants.RoleNames.Admin)) { NavigationManager.NavigateTo(Unauthorized); return; } await base.OnInitializedAsync(); }Oqtane 的权限模型基于角色与权限字符串如View、Edit、AdminModuleBase提供的User属性封装了当前用户的认证状态模块动作级授权应基于这些内置成员实现而非自行发明一套会话体系。通信安全所有 Web 通信使用HTTPS并为跨源访问配置合理的CORS 策略防止敏感接口被未授权域调用。十二、如何将该指令接入你的 Oqtane 工作区按照 docs/README.instructions.md 的说明自定义指令有两种落地方式复制到.github/copilot-instructions.md作为全局项目指令对整个仓库生效放入.github/instructions/目录创建任务级指令文件例如.github/instructions/my-oqtane-rules.instructions.md将本文讲解的规范内容放入其中。也可以直接在 VS Code / VS Code Insiders 中一键安装本仓库的 Oqtane 指令通过 docs/README.instructions.md 表格中的 Install 按钮。一旦安装进工作区指令即自动作用于 Copilot 对**/*.razor、**/*.razor.cs、**/*.razor.css文件的生成与修改后续所有新增模块代码都将遵循本文梳理的分层模式、命名约定与工程实践。总结instructions/oqtane.instructions.md 虽然篇幅精炼却完整覆盖了 Oqtane 模块开发的全部关键维度从 Blazor 代码风格、命名约定与语言特性到ModuleBase/ServiceBase/MVC Controller/Repository 四层链路的分层模式再到错误处理、性能优化、缓存、状态管理、测试调试与安全认证。它的价值在于把这些老手才知道的约定固化为 Copilot 的显式行为约束。在实际项目中建议将它与 instructions/blazor.instructions.mdBlazor 通用规范和 instructions/csharp.instructions.mdC# 基础规范配套启用形成Oqtane 特化 Blazor 通用 C# 底座的完整 AI 编码约束体系从而让 Copilot 产出的模块代码从一开始就符合 Oqtane 的架构预期。【免费下载链接】awesome-copilotCommunity-contributed instructions, agents, skills, and configurations to help you make the most of GitHub Copilot.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-copilot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考