用途:在 Bitwarden server 仓库中编写 C#/.NET 代码时,提供该项目的架构与编码约定,适用于创建命令、查询、服务或 API 端点等场景。
主要能力与约定:
- 命令查询分离(CQS):新功能使用离散动作类而非大型实体服务。命令为写操作,可改变状态并可能返回结果,按动作命名(如 RotateOrganizationApiKeyCommand);查询为读操作,返回数据且不改变状态。修改既有基于服务的代码时,应沿用文件已有模式,除非明确要求,否则不要重构为 CQS;若要求重构,仅限指定范围。
- 缓存:需要缓存时遵循 CACHING.md,使用 IFusionCache 而非 IDistributedCache。未要求时不要实现缓存;若用户描述的性能问题可能受益于缓存,可建议但需确认后再实现。
- GUID 生成:实体 ID 始终使用 CoreHelpers.GenerateComb(),不要用 Guid.NewGuid(),顺序 COMB 可避免 SQL Server 聚集索引碎片。
- 库结构:修改 src/Libraries/ 下代码时阅读 src/Libraries/LIBRARY.md。
- 注释:只写非显而易见的“为什么”,不写“是什么”;公共类型或成员用简洁的 /// XML 文档说明契约。
关键规则:DI 注册使用 TryAdd*(TryAddScoped、TryAddTransient)避免重复注册;使用文件作用域命名空间;启用可空引用类型,已知非空时用 !,构造时必须设置的属性用 required;异步方法加 Async 后缀;控制器操作返回 ActionResult<T>;测试使用 xUnit,采用 [Theory, BitAutoData](非 [AutoData])、SutProvider<T> 和 NSubstitute 的 Substitute.For<T>()。
限制:资料未提供安装命令、收费或平台信息;链接文档在运行时无法获取,故关键规则已内联。