诊断总表(KLSG)
格式:KLSG + 三位数字(SG = 编译期扩展诊断,生成器与分析器共用)。
逐包登记随 nupkg 分发(AnalyzerReleases.{Shipped,Unshipped}.md),家族单一事实源在
.github · RULES.md。
段位分配
| 段位 |
面 |
| KLSG001-013 |
Layout |
| KLSG045-049 |
Wire([WireArray] 045-048 + [WireField]/[WireMember] 宿主 049) |
| KLSG050-053 |
Wire([WireMessage]) |
| KLSG260-261 |
Wire([WireMessage] 字段 ID 冲突/越界——#186) |
| KLSG054-067 |
Cli |
| KLSG070-079 |
Endpoints(另见段位外 240-241) |
| KLSG080-094 |
Di |
| KLSG100-101 |
Display |
| KLSG110-112 |
Query |
| KLSG130-139、147-154、158-165 |
Analyzers(147-154 为契约串真值表/禁用模式/迁移指引,158 端序纪律,159-162 异步纪律,163-164 logger 尾随纪律,165 空 catch 说明注释实际占用) |
| KLSG140-146、155-157 |
Validation |
| KLSG200-249 |
Ef(已用 200-243;244-249 预留) |
| KLSG250-259 |
Http |
Cli(KLSG054-067)
| ID |
级别 |
规则 |
| KLSG054 |
Error |
命令路径冲突(重名/组名遮蔽/Route 覆写相撞/Route 与树内路径相撞) |
| KLSG055 |
Error |
非法命令名(空名/含路径分隔符) |
| KLSG056 |
Error |
命令参数未标注([CommandArg]/[CommandOption]/[CommandBody] 三选一) |
| KLSG057 |
Error |
不可绑定的参数形态(ref/out/in、指针、ref struct) |
| KLSG058 |
Error |
GET 命令带 body |
| KLSG059 |
Error |
命令标注宿主非法(游离 [Command]/重复标注/[CommandError] 非 Exception/body 超一个) |
| KLSG060 |
Error |
参数名占用生成器保留前缀(__tcsg_) |
| KLSG061 |
Error |
嵌套组未链接线且不可实例化 |
| KLSG062 |
Error |
参数类型不在绑定支持集(复杂对象请改 [CommandBody]) |
| KLSG063 |
Error |
loom_cli.* 配置键非法(坏值 fail-fast 回退缺省) |
| KLSG064 |
Error |
描述资源形态不完整(DescriptionKey 与 ResourceType 只给其一——回退链无法落地) |
| KLSG065 |
Error |
ResourceType 缺可访问的 ResourceManager(public 或同程序集 internal) |
| KLSG066 |
Error |
Confirm 命令的自动 --yes 与用户选项冲突 |
| KLSG067 |
Error |
[CommandGroup(Options)] 声明非法(嵌套组声明/选项类契约违例) |
Endpoints(KLSG070-079)
| ID |
级别 |
规则 |
| KLSG070 |
Error |
契约缺标记接口 |
| KLSG071 |
Error |
同动词路由重复 |
| KLSG072 |
Warning |
契约无端点配对(消费工程可关) |
| KLSG073 |
Error |
切面类型未实现 IAspect |
| KLSG074 |
Error |
契约结果类型与端点返回类型不一致 |
| KLSG075 |
Error |
端点方法形态非法 |
| KLSG076 |
Error |
route 模板路径参数与契约成员不匹配 |
| KLSG077 |
Error |
[FromLastEventId] 用于非 SSE 端点或参数类型非 string |
| KLSG078 |
Error |
LoomEndpoints* MSBuild 配置键值非法 |
| KLSG079 |
Error |
切面声明不可解析(派生切面特性无法确定切面类型/实参非编译期常量) |
越段续用(#62 入档——Endpoints 无自有空段,续用 Ef 预留块并双方对齐):
| ID |
级别 |
规则 |
| KLSG240 |
Error |
序列化底座不支持类型 |
| KLSG241 |
Error |
端点参数无法绑定 |
Di(KLSG080-094)
| ID |
级别 |
规则 |
| KLSG080 |
Error |
captive dependency |
| KLSG081 |
Error |
依赖未登记 |
| KLSG082 |
Error |
多实现无 Default |
| KLSG083 |
Error |
多个 Default |
| KLSG084 |
Error |
[SingleImplementation] 被违反 |
| KLSG085 |
Error |
标注误用 |
| KLSG086 |
Error |
严格档注册面越界 |
| KLSG087 |
Warning |
登记未消费 |
| KLSG088 |
Error |
依赖环 |
| KLSG089 |
Warning |
Transient 实现可释放接口 |
| KLSG090 |
Warning |
Singleton 注入 IServiceProvider |
| KLSG091 |
Warning |
约定表违规 |
| KLSG092 |
Error |
loom_di.* 配置键非法 |
| KLSG093 |
Error |
装饰器构造形态非法(装饰器特性无法解析接口/形态不匹配) |
| KLSG094 |
Warning |
装饰目标生命周期不确定(跨程序集/手写 Opaque 目标;loom_di.decorator_lifetime 可覆盖) |
Display(KLSG100-101)
| ID |
级别 |
规则 |
| KLSG100 |
Error |
[EnumDisplay] 元数据混源——同枚举 [Description] 与 [Display] 并用(歧义) |
| KLSG101 |
Error |
资源形态不完整(缺 Name / ResourceType 缺公共静态 ResourceManager)——culture 回退链无法落地 |
Query(KLSG110-112)
| ID |
级别 |
规则 |
| KLSG110 |
Error |
类级 [Filterable] 指向不存在或不可公开读的成员 |
| KLSG111 |
Error |
字段显式操作符越集(不在该类型支持集内) |
| KLSG112 |
Error |
字段类型不在支持集(string/bool/数值/DateTime·Offset/TimeSpan/Guid 及可空;对象成员未标 [EfComplex] 时带点路径指路) |
治理(KLSG130-139、147-154、158-165,Analyzers)
规则分析器族逐规则模板(#350——字段:级别/触发条件/违规样例/修正样例/豁免形态/配置键)。
级别为描述符缺省值,消费方一律以 dotnet_diagnostic.KLSGxxx.severity 按路径裁定(生产 error /
测试 none——等级旋钮不逐条重复);loom_* 配置键逐键全参考见 configuration.md,
完整可下载骨架实例见 skeleton.globalconfig。
分层依赖族(loom_layer.*——KLSG130-133)
KLSG130 禁用引用
- 级别:Warning
- 触发条件:using 指令或元数据引用命中
loom_layer.forbidden_reference 箭头对左值 → 右值禁列
- 违规样例:
using Contoso.Legacy;(声明 loom_layer.forbidden_reference = Contoso.App => Contoso.Legacy)
- 修正样例:删除 using,改经防腐层间接访问
- 豁免形态:无——依赖治理决策不宜自动放行(检测-only 立场)
- 配置键:
loom_layer.forbidden_reference = <左值程序集> => <目标1 | 目标2>(; 分隔多条)
KLSG131 零内部依赖违约
- 级别:Warning
- 触发条件:
loom_layer.zero_internal_refs 声明的程序集引用了 internal_assembly_prefix 圈定的族内其他程序集
- 违规样例:
Contoso.Contracts(零内部依赖声明)引用了 Contoso.Domain
- 修正样例:Contracts 只依赖 BCL,数据经调用方注入
- 豁免形态:无
- 配置键:
loom_layer.zero_internal_refs = <程序集>(必配 loom_layer.internal_assembly_prefix = <族前缀>,缺一即 KLSG139)
KLSG132 引用白名单越界
- 级别:Warning
- 触发条件:左值程序集引用了
loom_layer.allowed_reference 白名单之外的目标
- 违规样例:
Contoso.App 引用 Contoso.ThirdParty(不在白名单)
- 修正样例:治理批准后把目标补进白名单,或移除引用
- 豁免形态:无
- 配置键:
loom_layer.allowed_reference = <左值> => <白名单1 | 白名单2>
KLSG133 命名空间归属越界
- 级别:Warning
- 触发条件:左值程序集内类型命名空间不在
loom_layer.namespace_prefix 指定的归属前缀下
- 违规样例:
Contoso.App 程序集内声明 namespace Contoso.Misc(归属要求 Contoso.App)
- 修正样例:命名空间改为归属前缀(官方 CodeFix:命名空间声明改为规则首允许前缀)
- 豁免形态:无
- 配置键:
loom_layer.namespace_prefix = <左值> => <归属前缀>;分析器经 Diagnostic.Properties 传允许前缀给 fixer
禁用模式族(loom_forbidden.pack——KLSG134-138、152)
KLSG134 裸线程原语
- 级别:Warning
- 触发条件:pack 含
bare_threads 时构造/调用裸线程原语(new Thread/Timer/SemaphoreSlim/Mutex/ManualResetEvent(Slim)/PeriodicTimer、Thread.Sleep、Task.Run)
- 违规样例:
Task.Run(() => Pump());
- 修正样例:
TaskSink.Submit(_ => Pump());(后台受控任务一律 TaskSink;循环面走 BackgroundWorkerLoop)
- 豁免形态:
loom_forbidden.exempt.bare_threads = <FQN前缀>(实现组件本体);官方 CodeFix 插 pragma(带理由)
- 配置键:
loom_forbidden.pack 含 bare_threads;loom_forbidden.exempt.bare_threads;loom_forbidden.bare_threads.additional(追加类型,精确全名无通配)
KLSG135 热路径分配纪律
- 级别:Warning
- 触发条件:pack 含
hotpath_discipline 时,members_with([特性]) 标注方法体内出现 LINQ/装箱/字符串分配(启发式契约——漏报可能不承诺完备)
- 违规样例:标注方法内
items.Where(x => x.Ok).Count()
- 修正样例:手写循环 + 计数器(零分配)
- 豁免形态:作用域由标注圈定——不加标即不入检
- 配置键:
loom_forbidden.pack 含 hotpath_discipline(必配 loom_forbidden.scope.hotpath_discipline = members_with([<特性FQN>]),双向绑定缺一即 KLSG139)
KLSG136 禁止运行时反射
- 级别:Warning
- 触发条件:pack 含
reflection 时调用反射面成员(Type.GetMethod 族 / Activator.CreateInstance / Assembly.Load 族 / *Info.Invoke·GetValue·SetValue——接收者语义确认防同名误伤)
- 违规样例:
typeof(C).GetMethod("M")
- 修正样例:白盒走 InternalsVisibleTo;委托表/源生成替代
- 豁免形态:官方 CodeFix 插 pragma(带理由)
- 配置键:
loom_forbidden.pack 含 reflection
KLSG137 禁止同步强制等待异步
- 级别:Warning
- 触发条件:pack 含
sync_over_async 时的 .GetAwaiter().GetResult() / Task 族接收者 .Wait() / Task·ValueTask 泛型接收者 .Result
- 违规样例:
var v = SendAsync().GetAwaiter().GetResult();
- 修正样例:
var v = await SendAsync();(官方 CodeFix 改 await——仅 async 作用域内给修复)
- 豁免形态:
loom_forbidden.exempt.sync_over_async = <FQN前缀>;CodeFix 插 pragma
- 配置键:
loom_forbidden.pack 含 sync_over_async;loom_forbidden.exempt.sync_over_async
KLSG138 禁止丢弃 Task/ValueTask
- 级别:Warning
- 触发条件:pack 含
fire_and_forget 时的 _ = Task族表达式 / var _ = 声明 / 表达式语句裸调用(CS4014 的治理替代面)
- 违规样例:
_ = SendAsync();
- 修正样例:
TaskSink.Submit(_ => SendAsync());(ValueTask 走 SubmitFast——池化 token 不归还更危险)
- 豁免形态:
loom_forbidden.exempt.fire_and_forget = <FQN前缀>;CodeFix 改 TaskSink(编译内可解析 TaskSink 才给)
- 配置键:
loom_forbidden.pack 含 fire_and_forget;loom_forbidden.exempt.fire_and_forget
KLSG139 分析器配置非法
- 级别:Error(CompilationEnd)
- 触发条件:任意 loom_* 键未知/坏令牌/坏值/规则依赖双向缺失/同键异值冲突——fail-fast 绝静默
- 违规样例:
loom_forbidden.pack = bogus
- 修正样例:改合法令牌(逐键见 configuration.md 全键参考)
- 豁免形态:无——配置错误必须修
- 配置键:全部 loom_.
KLSG152 零拷贝丢失
- 级别:Warning
- 触发条件:pack 含
zero_copy_loss 时,ROM/ReadOnlyMemory 源上的 .ToArray() 且结果赋给同型 ROM 变量或传给 ROM 参数(高信号形态;byte[] 目标 = 合法拷贝不报)
- 违规样例:
ReadOnlyMemory<byte> copy = rom.ToArray();
- 修正样例:保持 ROM 一路透传(Wire 分派面);确需物化才显式 ToArray
- 豁免形态:无(启发式契约——仅报高信号)
- 配置键:
loom_forbidden.pack 含 zero_copy_loss
契约真值表族([StringContract] 标注驱动——KLSG147-151)
KLSG147 契约串 scheme/前缀形态非法
- 级别:Warning|触发条件:[StringContract] 常量串 scheme/前缀不符合真值表 DSL 形态|违规样例:缺 scheme 段的契约串|修正样例:补 scheme/前缀段|豁免形态:pragma 带理由|配置键:无(标注驱动)
KLSG148 契约串参数名未知
- 级别:Warning|触发条件:契约串引用真值表未声明的参数名|违规样例:
@{unknownParam}|修正样例:补参数声明或改名|豁免形态:pragma 带理由|配置键:无
KLSG149 契约串参数×域矩阵违规
- 级别:Warning|触发条件:参数组合落在真值表矩阵禁用格|违规样例:矩阵禁用格组合串|修正样例:改组合或扩矩阵|豁免形态:pragma 带理由|配置键:无
KLSG150 契约串参数值域违规
- 级别:Warning|触发条件:参数值不在 Values= 声明值域|违规样例:
level=9(值域 1-3)|修正样例:改值或扩值域|豁免形态:pragma 带理由|配置键:无
KLSG151 契约串参数交叉约束违规
- 级别:Warning|触发条件:违反 Requires/Excludes 交叉约束|违规样例:
a=1 而未满足 a=1 => b|修正样例:补齐被要求参数|豁免形态:pragma 带理由|配置键:无
迁移指引族(KLSG153-154)
KLSG153 QueryFieldCatalog.Build 迁移
- 级别:Warning
- 触发条件:调用过时的
QueryFieldCatalog.Build(typeof(契约))
- 违规样例:
QueryFieldCatalog.Build(typeof(OrderFilter))
- 修正样例:
new OrderFilterFilterIndex().ToCatalog()(官方 CodeFix 自动改写)
- 豁免形态:pragma 带理由
- 配置键:无
KLSG154 [Entity] 迁移
- 级别:Warning
- 触发条件:类型标注旧 [Entity](EfEntity 前代)
- 违规样例:
[Entity] public class Order(Ef 面)
- 修正样例:
[EfEntity(typeof(Db))](官方 CodeFix 改标注)
- 豁免形态:pragma 带理由
- 配置键:无
端序纪律族(KLSG158,常开)
KLSG158 端序敏感调用不在 ManualEndian 豁免面
- 级别:Error
- 触发条件:BinaryPrimitives 端序族 104 方法 + MemoryMarshal.Read/Write/Cast<byte,T> 调用点不在 [ManualEndian] 标注面(成员或外层类型任一标注即豁免;生成器发射面自带标注)
- 违规样例:
BinaryPrimitives.WriteInt32LittleEndian(span, 5);(无标注面)
- 修正样例:成员/类型标
[ManualEndian](语义确认本处确实端序敏感),或走 ScalarAccessors
- 豁免形态:[ManualEndian] 特性——零配置豁免面(豁免必须显式声明语义)
- 配置键:无(常开)
异步纪律族(loom_async.*——KLSG159-162)
KLSG159 异步方法缺 Async 后缀
- 级别:Warning
- 触发条件:返回 Task/ValueTask(含泛型与派生)/IAsyncEnumerable/IAsyncEnumerator(含派生接口)的方法名不以
Async 结尾
- 违规样例:
public Task DoWork() => Send();
- 修正样例:
public Task DoWorkAsync() => Send();(官方 CodeFix 方案级重命名——调用点同步改)
- 豁免形态:override/接口实现/Main/GetAsyncEnumerator 自动豁免;
loom_async.exempt.naming_suffix = <FQN前缀>
- 配置键:
loom_async.pack 含 naming_suffix;loom_async.scope.namespace = <前缀列表>(与 pack 双向绑定必配)
KLSG160 非异步方法带 Async 后缀
- 级别:Warning
- 触发条件:方法名以
Async 结尾且返回类型非可等待且非 async 关键字(误导调用方预期可等待)
- 违规样例:
public void ParseAsync() { }
- 修正样例:
public void Parse() { }(官方 CodeFix 方案级重命名)
- 豁免形态:override/接口实现自动豁免;
loom_async.exempt.naming_reverse
- 配置键:
loom_async.pack 含 naming_reverse;scope
KLSG161 async 方法返回 void
- 级别:Warning
- 触发条件:
async 方法返回 void(异常不可观测、调用方无法等待)
- 违规样例:
public async void DoWorkAsync() => await Send();
- 修正样例:
public async Task DoWorkAsync() => await Send();(官方 CodeFix 改返回类型)
- 豁免形态:事件处理器形态(
(object?, EventArgs 派生) 双参)自动豁免——void 是事件签名唯一形态;loom_async.exempt.async_void
- 配置键:
loom_async.pack 含 async_void;scope
KLSG162 末参数应为 CancellationToken
- 级别:Warning
- 触发条件:可等待返回方法缺 CT 或 CT 不在末位;
ct 必填与 ct = default 可选都合规(不校验默认值);重载对不做同族豁免(本方法参数面判定)
- 违规样例:
public Task SendAsync(string s) => SendCore(s);
- 修正样例:
public Task SendAsync(string s, CancellationToken ct = default) => SendCore(s);(官方 CodeFix 末位追加;CT 错位形态仅检测——改参顺序破坏位置实参调用点)
- 豁免形态:override/接口实现/Main 自动豁免;
loom_async.exempt.ct_last_param
- 配置键:
loom_async.pack 含 ct_last_param;loom_async.ct.parameterless = require | allow(零参方法口径,默认 require);scope
装配注入点 logger 尾随族(loom_logger.*——KLSG163-164)
KLSG163 可空可选 logger 族参数不在尾随块
- 级别:Error(常开——对齐 KLSG158 先例)
- 触发条件:可空可选 logger/factory 族参数(
= null 形态=装配注入点标志)后仍存在非注入位参数,或 logger 排在 factory 之前(factory 创建 logger——主依赖在前、logger 恒最后)
- 违规样例:
public C(string name, ILogger? logger = null, int retries = 3)
- 修正样例:
public C(string name, int retries = 3, ILogger? logger = null)(官方 CodeFix 重排声明——⚠️ positional 调用点源破坏自修)
- 豁免形态:扩展方法/必填 logger/合成成员自动豁免;类型集经
loom_logger.types/loom_logger.factory_types 配置(MEL 内置+追加;泛型闭合自动匹配;拒绝参数名启发式)
- 配置键:
loom_logger.types、loom_logger.factory_types
KLSG164 带参构造无 logger 族依赖
- 级别:Info(suggestion 位)
- 触发条件:
[RequireLoggerInjection] 标注类型的实例构造 ≥1 参数且 logger/factory 任一形态均不在场
- 违规样例:
public C(string name, int retries = 3)(标注类型内)
- 修正样例:
public C(string name, int retries = 3, ILogger? logger = null)(官方 CodeFix 尾补——候选类型分析器按编译可解析序裁定)
- 豁免形态:零参构造不入射程;未标注类型零报告("构造不传 logger"是正常写法——执法面 opt-in 显式圈定);标注不随继承传导(Inherited = false)
- 配置键:无(执法面 = 类型级特性标注,
KernLab.Loom.Abstractions 内置 [RequireLoggerInjection];loom_logger.scope.namespace 已移除——声明即 KLSG139 fail-fast)
吞没纪律族(KLSG165,常开零配置)
KLSG165 空 catch 缺说明注释
- 级别:Error
- 触发条件:catch 体为空且无伴随说明注释(catch 上一行/行尾/块内注释任一在场即合规——存在性判定,不判质量)
- 违规样例:
catch (ObjectDisposedException) { }
- 修正样例:
catch (ObjectDisposedException) { } // ★ 与 Stop 竞速——已释放 = 排干已无意义(写明为什么安全)
- 豁免形态:无——无说明的空 catch 无可辩护形态;生成代码不分析
- 配置键:无(常开零配置)
Validation(KLSG140-146、155-157)
| ID |
级别 |
规则 |
| KLSG140 |
Error |
[Range] 标注在非数值属性上(含 Type 重载边界) |
| KLSG141 |
Error |
[RegularExpression] 正则预解析失败——写错即编译错误,不等到运行时 |
| KLSG142 |
Error |
校验器契约未声明端点——配对悬空(T2 接线无槽位) |
| KLSG143 |
Error |
IValidatable 实现带 I/O 形态(纯函数逃生口不准有副作用) |
| KLSG144 |
Error |
契约校验图含环(嵌套递归不可收敛) |
| KLSG145 |
Warning |
DataAnnotations 注解不在 T1 支持集或标注类型不匹配(绝静默)/RequiredIf 标注在非可空值类型上(恒存在,不生成规则) |
| KLSG146 |
Warning |
ErrorMessageResourceType/Name 本地化形态不完整(回退字面量/缺省文案) |
| KLSG155 |
Error |
交叉字段比较目标无效(缺失/不是字段或属性/自引用/不可读) |
| KLSG156 |
Error |
交叉字段比较两侧类型不可比较(核心类型不匹配或不在支持集) |
| KLSG157 |
Error |
条件必填标志无效(缺失/不是字段或属性/自引用/不可读/类型非法) |
Ef(KLSG200-249)
已用 200-242;250-259 归 Http(段位边界见 RULES.md 与上方段位分配表)。
上下文绑定与实体形态:
| ID |
级别 |
规则 |
| KLSG200 |
Error |
实体缺主键 |
| KLSG201 |
Error |
租户实体绑定到未挂租户约定的上下文(配对锁) |
| KLSG202 |
Error |
多上下文绑定歧义 |
| KLSG203 |
Error |
绑定目标非 DbContext |
| KLSG204 |
Error |
键策略与键类型冲突 |
| KLSG205 |
Error |
AuditTrail 特征无 sink 可落 |
| KLSG206 |
Error |
列名覆盖与真实属性撞名 |
| KLSG207 |
Error |
同实体同上下文重复绑定 |
| KLSG208 |
Error |
绑定上下文不可合并(非本源声明) |
| KLSG210 |
Error |
同实体混用绑定形态 / 名称绑定歧义 |
| KLSG212 |
Error |
组合键序号非法 |
| KLSG213 |
Error |
组合键与键策略并标 |
| KLSG221 |
Error |
watch 字段缺失或处理器签名不匹配 |
| KLSG224 |
Error |
ILoomDbContext 壳的基类非 DbContext |
| KLSG243 |
Error |
上下文须声明在命名空间层——嵌套 DbContext 不支持生成合并(#342 防呆) |
查询治理与投影:
| ID |
级别 |
规则 |
| KLSG211 |
Warning |
IgnoreQueryFilters 全量旁路(配合运行时政策,缺省 Throw) |
| KLSG214 |
Warning |
裸逃逸口调用(raw SQL / 批更新 / 批删——配合白名单) |
| KLSG215 |
Error |
并发机制重复声明 |
| KLSG216 |
Warning |
投影成员无匹配 |
| KLSG217 |
Error/Warning |
投影成员类型有损转换(不可无损转换) |
| KLSG218 |
Error |
投影别名目标缺失 |
| KLSG219 |
Error |
投影绑定到未注册实体 |
| KLSG220 |
Error |
同上下文表名冲突(命名策略转换后同名同拦) |
| KLSG232 |
Warning |
投影成员引用 [EfNotMapped] 源成员 |
动态视图与声明词汇(DCL):
| ID |
级别 |
规则 |
| KLSG222 |
Warning |
视图 SQL 引租户表无租户谓词 |
| KLSG223 |
Error |
视图引用名无法解析 |
| KLSG225 |
Error |
实体内唯一索引名冲突 |
| KLSG226 |
Error |
统一列特性与细粒度特性同维度双标(二选一) |
| KLSG227 |
Error |
常量默认与 SQL 默认双设 |
| KLSG228 |
Error |
精度声明非法(非 decimal / scale > precision) |
| KLSG229 |
Error |
写一次标在键/并发戳属性 |
| KLSG230 |
Error |
计算列与可写声明冲突 |
| KLSG231 |
Error |
[EfNotMapped] 与映射声明冲突 |
| KLSG233 |
Error |
默认值字面量无法按属性类型解析 |
继承与 ComplexType(INH / CT):
| ID |
级别 |
规则 |
| KLSG234 |
Error |
鉴别器定制与 Tpt/Tpc 策略互斥 |
| KLSG235 |
Error |
继承策略标在派生实体(须基类根) |
| KLSG236 |
Error |
复杂类型集合形态不支持(指路 [EfJson]) |
| KLSG237 |
Error |
ComplexType 与 [EfJson] 同属性双标 |
| KLSG238 |
Error |
复杂类型成员标 [EfKey](无键) |
| KLSG239 |
Error |
复杂类型嵌套超深(上限 4) |
| KLSG242 |
Warning |
冻结模型过期——optimize 产物缺当前实体映射成员(重跑 loom ef optimize) |
Http(KLSG250-259)
| ID |
级别 |
规则 |
| KLSG250 |
Error |
空客户端契约([HttpApi] 接口无任何动词标注方法——P2 接口主形态) |
| KLSG251 |
Error |
路由模板与参数不匹配(占位符无参数 / [Path] 无占位符 / catch-all 非 string / 可选段非可空) |
| KLSG252 |
Error |
HTTP 契约类型不在支持集(返回/参数/序列化闭包不可达——P2 边界:流/集合结果/SSE 归 P4) |
| KLSG253 |
Error |
请求头声明非法([HttpHeader] 名/值空或含换行) |
| KLSG254 |
Error |
请求体绑定非法(多 [Body] / 无体动词带 [Body] / 有体动词缺 [Body]) |
| KLSG255 |
Error |
参数形态不支持(多绑定特性/未标注复杂类型/重复查询名/[Query] 非标量或集合/[Header] 非 string) |
| KLSG256 |
Error |
表单绑定非法([FormFile] 用于非 Multipart / 表单方法未标注模式 / 表单参数类型不在支持集) |
| KLSG257 |
Error |
接口方法形态非法(非 public/静态/泛型/ref-out/重载/缺动词标注/同名客户端冲突) |
| KLSG258 |
Warning |
未提供 Service/BaseAddress(须由 AddLoomHttpClient 的 LoomHttpOptions.Services 补全) |
| KLSG259 |
Error |
[HttpApi] 记录形态非法(非 record / 缺 IHttpApi<TResult>) |
基础面
| ID |
面 |
规则 |
| KLSG001-014 |
Layout |
标注用法/字段/布局/校验/嵌套/OrFlags·IsEmpty 目标/union 判别(014——#194)/生成失败 |
| KLSG045-049 |
Wire |
[WireArray] 族(045-048)+ [WireField]/[WireMember] 宿主(049) |
| KLSG050-053 |
Wire |
[WireMessage] 族 |
| KLSG260-261 |
Wire |
[WireMessage] 字段 ID 冲突/越界(#186) |
| KLSG054-067 |
Cli |
命令面规则(见上方 Cli 段明细) |
| KLSG140-146 |
Validation |
校验段(见上方 Validation 段明细) |
| KLSG250-259 |
Http |
声明式 HTTP 客户端(见上方 Http 段明细) |
消费方纪律
[**/*.cs]
dotnet_diagnostic.KLSG087.severity = none # 测试/探针按需关闭
- Warning ≠ 可忽略——家族零警告红线下 Warning 同样致命,"可配置关闭"才是其语义。
- 受控豁免用
#pragma warning disable <ID> 并注明理由;改名时必须同步 pragma 里的 ID。
- 新增规则两步:包内
AnalyzerReleases 登记 + 家族 RULES.md 补行。