Elsa Core Pull Request 质量标准清单：编码规范、测试要求与 `var` 风格约定的完整指南

后端工作流自动化流程编排低代码【免费下载链接】elsa-coreThe Workflow Engine for .NET项目地址https://gitcode.com/gh_mirrors/el/elsa-core点击查看免费下载导读本文档是 Elsa WorkflowsThe Workflow Engine for .NET开源仓库中面向贡献者的Pull Request 质量标准清单PR Quality Standard Checklist的完整解读与源码级展开。它定义了提交到 elsa-core 仓库的每一个 PR 必须满足的编码、文档、测试、评审、CI、性能安全与依赖兼容门槛是参与官方 Bounty 悬赏计划见 bounty-footer.md 与 bounty-announcement-template.md以及日常社区贡献的“验收红线”。读完本文你将掌握如何按仓库规范组织 C# 代码、何时使用var及背后的设计理由、如何编写通过 CI 的单元/集成测试以及如何对照仓库现有配置.editorconfig、Directory.Build.props、测试基线逐项自检自己的提交。一、编码规范Coding Standards1.1 以微软官方编码指南为基线且有一处明确例外清单的第一条要求 PR 遵循Microsoft 官方 C# 编码指南.NET coding conventions仓库同时声明了一处刻意偏离统一使用var进行变量声明。这一约定并非口头要求而是写进了仓库的机器可执行配置中。根目录的 .editorconfig 明确设置了三条var偏好规则# var preferences csharp_style_var_elsewhere true csharp_style_var_for_built_in_types true csharp_style_var_when_type_is_apparent true同时doc/codebase/CONVENTIONS.md 的“Formatting and Linting”一节也写明“varpreferred”并规定格式校验工具为 Roslyn.editorconfig设置格式化命令为dotnet format Elsa.sln。1.2 仓库级编码约定速查来自 CONVENTIONS.md条目规则示例文件命名C# 类型使用 PascalCaseExternalAuthenticationBroker.cs方法命名PascalCase异步方法以Async结尾CompleteCallbackAsync接口命名I前缀IExternalIdentityProvisioner局部变量/参数camelCasesignedInAt此外.editorconfig 还约束了4 空格缩进indent_size 4、行宽上限 420花括号强制csharp_prefer_braces true文件作用域命名空间csharp_style_namespace_declarations file_scoped:warningusing 置于命名空间外csharp_using_directive_placement outside_namespace且系统指令优先排序接口命名I前缀、类型与方法 PascalCase 均为命名规则suggestion 级别。二、文档要求Documentation清单要求所有公共成员提供 XML 注释XML comments provided for all public members复杂逻辑必须配内联注释Inline comments explain complex logic。这两条同样有仓库配置的硬性支撑。根目录 Directory.Build.props 中GenerateDocumentationFiletrue/GenerateDocumentationFile AnalysisModeDocumentationDefault/AnalysisModeDocumentation AnalysisLevelDocumentationlatest/AnalysisLevelDocumentation即所有项目默认生成 XML 文档文件并将文档分析器开到latest级别。同时该文件通过NoWarn放行了CS1591缺少公共成员注释的警告与CS0162、CS0618过时 API 警告用于迁移期向后兼容因此 XML 注释更多是“质量红线”而非“编译死线”——这正是为什么 PR 清单把它单列为一项需要人工确认的检查点。补充的仓库级约定来自 doc/codebase/CONVENTIONS.md还包括日志使用Microsoft.Extensions.Logging与结构化消息模板对外响应 DTO 不得包含敏感 token 与 subject 哈希脱敏行为由专门测试覆盖。三、测试要求Testing清单的三个测试检查点分别是单元测试覆盖关键函数Unit tests cover critical functions集成测试覆盖主要工作流Integration tests for major workflows高代码覆盖率High code coverage。3.1 仓库的测试分层与目录在 elsa-core 中测试按层级物理隔离在test/下见 AGENTS.md 的 Repository Structure 与 doc/qa/test-guidelines.md层级目录目标单元测试test/unit/单类逻辑活动、表达式求值器、序列化器、服务提供者快、无持久化集成测试test/integration/多个 Elsa 子系统协同invoker activities registries进程内组件测试test/component/持久化行为、Journal/实例断言、跨生命周期边界的 bookmark 恢复性能测试test/performance/吞吐与性能基准各模块都有对应测试项目例如test/unit/Elsa.Activities.UnitTests、test/integration/Elsa.Workflows.IntegrationTests、test/component/Elsa.Workflows.ComponentTests。3.2 “高代码覆盖率”的量化基线仓库用 test/Directory.Build.props 把“高覆盖率”落成了可执行的数值CollectCoverage Condition$(CollectCoverage) true/CollectCoverage CoverletOutputFormat Condition$(CoverletOutputFormat) cobertura,lcov,opencover/CoverletOutputFormat Threshold Condition$(Threshold) 10/Threshold ThresholdType Condition$(ThresholdType) line/ThresholdType ThresholdStat Condition$(ThresholdStat) total/ThresholdStat即每个测试项目默认开启 coverlet 收集输出cobertura/lcov/opencover三种格式并设定了行覆盖率阈值默认 10%Threshold10、ThresholdTypeline、ThresholdStattotal超过阈值失败。同一文件中还集中引入了 xUnit、Moq、NSubstitute、Microsoft.AspNetCore.Mvc.Testing、coverlet.msbuild等测试基础设施并默认Using IncludeXunit。3.3 测试风格约定doc/codebase/CONVENTIONS.md 的“Testing Conventions”一节规定测试使用 xUnit优先使用真实的内存实现NSubstitute 仅在外部边界或昂贵边界使用集成测试覆盖率默认 10%/项目。推荐的测试辅助设施包括ActivityTestFixture活动单元测试、WorkflowTestFixture与IWorkflowRunner.RunAsync集成测试、AsyncWorkflowRunner与IWorkflowInstanceStore组件测试完整辅助方法速查表见 doc/qa/test-guidelines.md 的“Test Helpers Reference”。3.4 本地运行测试的命令按 AGENTS.md 与 doc/qa/test-guidelines.md# 构建解决方案 dotnet build Elsa.sln # 运行全部测试 dotnet test Elsa.sln # 只跑某个测试项目推荐迭代期使用 dotnet test test/unit/Elsa.Workflows.Core.UnitTests/Elsa.Workflows.Core.UnitTests.csproj # 检查测试稳定性连跑 10 次排查 flaky dotnet test --no-build -- repeat 10 # 需要显式格式化时 dotnet format Elsa.sln四、代码评审Code Review清单要求提交前完成同行评审Peer review completed通过自动化代码分析Passes automated code analysis。自动化分析在仓库里有明确落地根 Directory.Build.props 开启了NuGetAuditNuGetAuditModeall审计全部依赖包漏洞、EnableTrimAnalyzerIL 裁剪分析器与文档分析器AGENTS.md 的“Review Checklist”要求提交前核实项目/解决方案可构建、相关单元或集成测试通过、公共 API 或行为变更已文档化、新代码符合 nullable 注解与既有风格、未改动无关文件。这些正是 PR 评审阶段人工核对的核心项。五、持续集成Continuous Integration清单要求CI 检查全绿构建、测试、风格检查CI checks pass: builds, tests, style checks。对应地仓库定义了完整 CI 命令链AGENTS.md默认构建目标./build.shNUKE 自动化、NUKE 测试目标./build.sh Test、直接构建dotnet build Elsa.sln、全量测试dotnet test Elsa.sln。文档生成方面AGENTS.md 还特别注明doc/adr/toc.md是生成文件必须运行scripts/adr/generate-toc.sh后提交且 CI 会执行--check校验其是否最新——这也属于“风格/一致性检查”的一部分。六、性能与安全Performance and Security性能在必要处进行优化Performance is optimized where necessary遵循安全最佳实践Security best practices followed。仓库层面的性能与安全实践可从配置与文档中印证Directory.Build.props 开启NuGetAudit与EnableTrimAnalyzer分别针对供应链安全与发布体积/裁剪安全仓库设有test/performance/Elsa.Workflows.PerformanceTests性能测试项目性能回归有专门测试入口doc/codebase/CONVENTIONS.md 规定对外 DTO 省略 subject 哈希与敏感 token脱敏由专门测试覆盖属于安全编码红线。七、依赖与兼容性Dependencies and Compatibility依赖被管理且保持更新Dependencies are managed and up to date破坏性变更必须伴随文档No breaking changes without documentation。仓库通过**中央包管理Central Package Management**落实依赖治理Directory.Packages.props 集中定义包版本AGENTS.md 明确“不要在各项目文件中引入临时版本除非仓库已对该包采用此模式”并提醒“本仓库多目标框架、多模块升级包需格外谨慎”。多目标框架由 src/Directory.Build.props 集中管理TargetFrameworksnet8.0;net9.0;net10.0/TargetFrameworks同时根 Directory.Build.props 设定LangVersionlatest、Nullableenable、ImplicitUsingsenable并放行CS0618过时 API 警告用于“迁移期向后兼容”——这正体现了“破坏性变更需有过渡与文档”的仓库态度。公共 API 变更必须更新文档这一点同时写入了 AGENTS.md 的工作规则“Update documentation when changing externally visible behavior, configuration, APIs, or developer workflows.”八、仓库为什么统一使用var完整理由剖析清单专门为“统一使用var”附上了 Rationale 小节共四条理由同时引用了 Chris Schaller 的博客文章To var or not to var作为外部参考。下面结合仓库实况逐条展开1. 更干净的代码Cleaner Codevar消除了右值类型已经显而易见的重复声明噪音。例如在 LINQ 查询与泛型表达式场景中显式类型往往冗长且与逻辑无关var让代码更聚焦。仓库的.editorconfig将csharp_style_var_elsewhere、csharp_style_var_for_built_in_types、csharp_style_var_when_type_is_apparent全部置为true说明这一偏好贯穿整个代码库。2. 现代 IDE 的悬停提示消除可读性顾虑Modern IDEsVisual Studio 等 IDE 的悬停hover/tooltip功能可以即时显示推断类型因此“不知道变量的类型”在现代开发环境中不再是问题。这也是仓库选择把var写进.editorconfig作为强制风格而非口头建议的现实前提。3. 一致性与可维护性Consistency and Maintenance全库统一var降低开发者心智负担重构时若右侧类型变化无需同步修改声明行。这一点在 elsa-core 这样规模庞大src/modules/下数十个模块、多目标框架的仓库中收益尤其明显——类型变化是常态统一风格能让 diff 聚焦在真正的逻辑变更上。4. 聚焦逻辑而非类型细节Focus on Logic在复杂表达式与 LINQ 查询中类型往往冗长且不是关注重点。var让开发者把注意力放在“这段代码做了什么”而不是“它的静态类型拼写是什么”。仓库test/下的实际测试代码也大量遵循此风格例如 doc/qa/test-guidelines.md 中的示例var result await runner.RunAsync(workflow);、var fixture new ActivityTestFixture(setVariable);均可作为“就地取材”的风格范本。需要注意的边界这里的“统一使用var”是清单的显式例外项它偏离了微软官方指南中“仅在类型不明显时使用 var”的默认建议。因此评审者在对照清单时不应把“显式写出类型”当作加分项或扣分项而应以仓库.editorconfig为准——var是默认风格。附如何把清单落成一次可自检的提交流程结合 CONTRIBUTING.md 与 AGENTS.md 的工作规则推荐的 PR 自检顺序为编码对照 .editorconfig 与 doc/codebase/CONVENTIONS.mdPascalCase/camelCase、文件作用域命名空间、var偏好、usings 排序文档确认公共成员有 XML 注释、复杂逻辑有内联注释GenerateDocumentationFile已在 Directory.Build.props 开启测试按 doc/qa/test-guidelines.md 的分层决策规则选择层级——内部逻辑写单元测试、组件协作写集成测试、端到端持久化行为写组件测试用dotnet test验证并满足默认覆盖率门槛评审对照 AGENTS.md 的 Review Checklist确认构建、测试、文档、nullable 注释与“未改动无关文件”五项全部通过CI确保./build.sh、dotnet build Elsa.sln、dotnet test Elsa.sln等命令链全绿含 ADR 目录scripts/adr/generate-toc.sh --check的一致性校验性能与安全确认无性能回归可参考test/performance/项目遵守安全编码约定敏感信息脱敏、不引入含已知漏洞的依赖NuGetAudit会辅助把关依赖与兼容包版本变更走 Directory.Packages.props 中央管理若存在破坏性变更必须同步更新文档并说明迁移路径。若你的提交是针对 Bounty 悬赏任务相关模板见 bounty-footer.md 与 bounty-announcement-template.md这份清单同样是评审命中的硬性标准满足质量门槛的解决方案才可能被判定为“成功解决”并进入奖励流程。赞分享后端工作流自动化流程编排低代码【免费下载链接】elsa-coreThe Workflow Engine for .NET项目地址https://gitcode.com/gh_mirrors/el/elsa-core点击查看免费下载相关推荐Gravitino代码规范编码风格与质量要求Gravitino代码规范编码风格与质量要求 引言 在大型开源项目中统一的代码规范是保证代码质量、可维护性和团队协作效率的关键。Apache Graviti大数据数据目录数据治理数据湖后端如何快速上手SparseDrive10分钟搭建自动驾驶开发环境如何快速上手SparseDrive10分钟搭建自动驾驶开发环境 SparseDrive是一个基于稀疏场景表示的端到端自动驾驶解决方案能够帮助开发者快速构建和3分钟搞定RTL8188EU无线网卡Linux驱动安装完整指南3分钟搞定RTL8188EU无线网卡Linux驱动安装完整指南 还在为Linux系统无法识别RTL8188EU无线网卡而烦恼吗这款专为Realtek RTL驱动开发嵌入式网络上一篇Dash性能优化终极指南10个实用技巧让大型数据应用飞起来下一篇tmux-yank代码实现原理从Shell脚本到系统剪贴板的完整流程分析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考