GJJ.Keystone.ArchitectureGuard 4.2.2

GJJ.Keystone.ArchitectureGuard

面向 GJJ 微服务的架构守护测试库。在 *.Tests 项目里跑，违规即让单元测试失败、CI 红灯； 报告带颜色、严重度分组、修复建议、文件超链接（IDE 可点击跳转）。

核心承诺：零运行时依赖（不引 ASP.NET / Microsoft.Extensions.Logging），只在 CI / 本地测试期参与。

适用版本：3.0.7+

为什么独立成包

• GJJ.Keystone.Abstractions 应保持精简，只放契约
• GJJ.Keystone.Toolkit 提供运行时无关的通用工具代码
• GJJ.Keystone.AspNetCore 引入了 ASP.NET Core 概念，而本库的职责之一恰好是让非 Web 层免受这些概念污染

把架构规则放在独立程序集里，可避免把 Web 依赖拉入只需要在 CI / 测试期检查的项目。

速查

一、模块全景

┌──────────────────────────────────────────────────────────────┐
│   ArchitectureGuardOptions                                   │
│   - RootDirectory                                            │
│   - IgnoredDirectoryNames / IgnoredRelativeFilePaths        │
│   - HttpContextProtectedLayers                               │
│   - ControlledContextFieldNames                              │
│   - ViewModelDirectoryNames                                  │
│   - AspNetCoreProtectedProjectSegments                       │
└──────────────────────────────────────────────────────────────┘
       ↓ ArchitectureGuard.Scan / ScanGjjDefaults
┌──────────────────────────────────────────────────────────────┐
│   IArchitectureRule × 18                                     │
│   - 文本扫描（SourceLineReader 剥离注释 / 字符串）            │
│   - PathClassifier 判定层（Application/Infrastructure/...）  │
│   - 每条规则带 DefaultSeverity + Suggestion                  │
└──────────────────────────────────────────────────────────────┘
       ↓
┌──────────────────────────────────────────────────────────────┐
│   ArchitectureGuardResult                                    │
│   - Violations: IReadOnlyList<ArchitectureViolation>         │
│   - Format(): 带颜色 / 分组 / 修复建议的报告                  │
│   - ThrowIfFailed(): xUnit 断言失败入口                       │
└──────────────────────────────────────────────────────────────┘
       ↓ 进入 xUnit 测试输出
       (终端: 渲染颜色 / IDE: 渲染加粗下划线斜体)

二、规则全集（19 条）

按主题分组。每条规则一旦命中：

• 严重度 ≥ Error 的违规默认让 ThrowIfFailed() 抛 InvalidOperationException
• 严重度 = Warning / Info 不阻断（但会显示在报告里）

如何调整某条规则的严重度：在调用 Scan(...) 时传入自定义 IArchitectureRule 替换默认实例，覆写 DefaultSeverity。

分层 / DTO 边界（6 条）

异步 / 通用代码风险（2 条）

安全 / 合规（7 条）

架构纪律（4 条）

GJJ016 特别说明

GJJ016 与 GJJ.Keystone.AspNetCore/Auth/JwtAuthExtensions.cs 的 AddJwtAuth 协同设计：

public static IServiceCollection AddJwtAuth(
    this IServiceCollection services,
    Action<JwtAuthOptions> configure,
    bool requireAuthenticatedByDefault = true,   // ★ 默认 true
    ILogger? startupLogger = null)
{
    // ...
    services.AddAuthorization(options =>
    {
        if (requireAuthenticatedByDefault)
        {
            options.FallbackPolicy = new AuthorizationPolicyBuilder()
                .AddAuthenticationSchemes(JwtBearerDefaults.AuthenticationScheme)
                .RequireAuthenticatedUser()
                .Build();
        }
    });
}

关键事实：当 requireAuthenticatedByDefault = true（默认），ASP.NET Core 授权管线注册 FallbackPolicy = RequireAuthenticatedUser()——这意味着所有未标注授权属性的端点都默认需要认证。

因此 Controller 三种状态的真实含义：

GJJ016 严重度自适应：规则会扫描全仓库源码自动决定严重度，无需手动配置：

实现见 Rules/MissingAuthorizeRule.cs:DetectEffectiveSeverity。

强制升级到 Error（绕过自动检测）示例：

// 不论 FallbackPolicy 状态，强制所有 Controller 必须显式标授权
public sealed class StrictMissingAuthorizeRule : IArchitectureRule
{
    private readonly MissingAuthorizeRule _inner = new();
    public string RuleId => _inner.RuleId;
    public string Description => _inner.Description;
    public ArchitectureSeverity DefaultSeverity => ArchitectureSeverity.Error;
    public IEnumerable<ArchitectureViolation> Evaluate(ArchitectureScanContext ctx)
        => _inner.Evaluate(ctx).Select(v => v with { Severity = ArchitectureSeverity.Error });
}

// 装配
var rules = GjjDefaultArchitectureRules.Create()
    .Where(r => r.RuleId != "GJJ016")
    .Concat(new[] { new StrictMissingAuthorizeRule() })
    .ToArray();
ArchitectureGuard.Scan(options, rules).ThrowIfFailed();

三、典型用法

3.1 最简调用（推荐起点）

using GJJ.Keystone.ArchitectureGuard;

public sealed class ArchitectureGuardTests
{
    [Fact]
    public void GJJ_default_architecture_rules_should_pass()
    {
        var options = new ArchitectureGuardOptions
        {
            RootDirectory = LocateRepositoryRoot(),
        };

        ArchitectureGuard.ScanGjjDefaults(options).ThrowIfFailed();
    }

    private static string LocateRepositoryRoot()
    {
        var dir = new DirectoryInfo(AppContext.BaseDirectory);
        while (dir != null)
        {
            if (dir.EnumerateFiles("*.sln").Any())
                return dir.FullName;
            dir = dir.Parent;
        }
        throw new DirectoryNotFoundException("repo root (含 *.sln) 未找到");
    }
}

ThrowIfFailed() 在违规时抛 InvalidOperationException，消息体就是带颜色 + 分组 + 修复建议的报告。

3.2 自定义规则集（跳过部分规则 / 改严重度）

var result = ArchitectureGuard.Scan(options,
    new ForbiddenHttpContextDependencyRule(),
    new SmEncryptionRuntimeChecksRule(),
    // ...只跑你关心的规则
    );

3.3 项目特有受控字段（在默认集合上扩展）

options.ControlledContextFieldNames.UnionWith(new[]
{
    "DbPointCode",   // 多数据库路由
    "ChannelCode",   // 渠道标识
    "SubjectId",     // 业务主体 ID
});

3.4 自定义忽略目录（如本项目特殊产物目录）

options.IgnoredDirectoryNames.Add(".claude");
options.IgnoredDirectoryNames.Add("artifacts");

四、输出格式与颜色

4.1 实际样例（带颜色版会在终端 / Rider / VS Code 渲染）

================================================================================
  GJJ Architecture Guard — 23 violation(s) across 4 rule(s)        ← 加粗
================================================================================

  [CRITICAL] 1 violation(s)                                        ← 亮红+粗
--------------------------------------------------------------------------------
  GJJ005  SMEncryptionMiddleware 必须同时具备 nonce 去重 ...         ← 亮红+粗
    Demo/Security/SmEncryptionMiddleware.cs:1                      ← 下划线
      SMEncryptionMiddleware 缺少 nonce 一次性消费校验……
    fix: 注入 INonceStore 并在解密前调用 TryConsumeNonceAsync...   ← 斜体

  [ERROR]    1 violation(s)                                        ← 红+粗
--------------------------------------------------------------------------------
  GJJ001  非 Web 层代码不得依赖 HttpContext 相关 API。
    Demo.Application/News/NewsService.cs:7
      非 Web 层禁止依赖 HttpContext 相关 API 'HttpContext'……
    fix: 在 Controller 内提取所需值（OperatorId、ClientIp 等）……

  [WARNING]  1 violation(s)                                        ← 黄+粗
--------------------------------------------------------------------------------
  GJJ003  DTO 不得跨层泄漏……
    Demo.Infrastructure/News/NewsRepository.cs:14
      ...
    fix: ...

================================================================================
  Summary: Critical=1  Error=1  Warning=1  Info=0                  ← 各色加粗
================================================================================

4.2 颜色控制

4.3 ViolationFormatOptions

public sealed record ViolationFormatOptions
{
    public bool? UseColor { get; init; }            // null = 自动检测
    public bool  ShowSuggestions { get; init; } = true;
    public bool  ShowPassingBanner { get; init; }   // 通过时也打印"PASSED"横幅
}

五、基线管理（IgnoreFiles）

历史违规一次性塞进 baseline 让 CI 绿；新写违规当场拦截。

var options = new ArchitectureGuardOptions { RootDirectory = root };

options.IgnoreFiles(
    // GJJ001：历史代码非 Web 层依赖 HttpContext
    "GJJ.UniServiceHub.Application/Admin/AdminService.cs",
    "GJJ.UniServiceHub.Infrastructure/Admin/AdminCenterClient.cs",
    // GJJ002：响应 ViewModel 含 createTime（出参视为合理）
    "GJJ.UniServiceHub.Api/Controllers/.../SysUserInfoVM.cs"
);

ArchitectureGuard.ScanGjjDefaults(options).ThrowIfFailed();

5.1 何时加 baseline

• 历史代码违规，团队没排期治理
• 文本扫描误报（如 HttpRequestMessage 字面量含 "HttpRequest" 子串）
• 框架/平台规定的合法跨层（特殊代理转发）

5.2 何时不能加 baseline

• 新代码引入的违规 → 必须修代码
• Critical 级别（GJJ005/007/008/009/011/017）→ 改代码或评审豁免，不应静默

baseline 是技术债，应随 sprint 逐项清理。

六、扩展自定义规则

6.1 实现 IArchitectureRule

using GJJ.Keystone.ArchitectureGuard;
using GJJ.Keystone.ArchitectureGuard.Internal;

public sealed class MyProjectSpecificRule : IArchitectureRule
{
    private const string FixSuggestion = "改用 IGjjCurrentUser 注入，不直接读 HttpContext.User。";

    public string RuleId => "GJJ100";
    public string Description => "禁止在 Application 层直接读 HttpContext.User.Claims。";
    public ArchitectureSeverity DefaultSeverity => ArchitectureSeverity.Error;

    public IEnumerable<ArchitectureViolation> Evaluate(ArchitectureScanContext context)
    {
        foreach (var file in context.SourceFiles.Where(PathClassifier.IsApplication))
        {
            foreach (var (lineNumber, text) in SourceLineReader.NonCommentLines(file))
            {
                if (!text.Contains("HttpContext.User", StringComparison.Ordinal)) continue;

                yield return new ArchitectureViolation(
                    RuleId, file.RelativePath, lineNumber,
                    "Application 层禁止直接读 HttpContext.User.Claims。",
                    Severity: DefaultSeverity,
                    Suggestion: FixSuggestion);
            }
        }
    }
}

6.2 接入

ArchitectureGuard.Scan(options,
    new MyProjectSpecificRule(),
    // 还可以叠加默认集
    new ForbiddenHttpContextDependencyRule(),
    // ...
).ThrowIfFailed();

6.3 助手 API（Internal）

测试项目通过 InternalsVisibleTo 可用，也是写自定义规则的好朋友：

6.4 何时该用 ClassScanner

如果你的规则需要回答**"某个类是否带某 attribute"或"某个类是否包含某成员"**这种 类级问题——用 ClassScanner。

它已处理三类共性边界：

• 一文件多类（不同类各自独立判定）
• partial class 分散在多文件（attribute 标在任一分片都算）
• 注释 / 字符串中的伪 attribute（不误判）

不要在新规则里再写"扫文件全文找 attribute"——交给 ClassScanner。

七、严重度模型

ThrowIfFailed() 默认在任意违规时抛异常（包含 Warning）。如果只想 Error 及以上阻断 CI，自己控制：

var result = ArchitectureGuard.ScanGjjDefaults(options);
var blocking = result.Violations
    .Where(v => v.Severity >= ArchitectureSeverity.Error)
    .ToList();

if (blocking.Count > 0)
    throw new InvalidOperationException(result.Format());

八、已知限制

8.1 文本扫描，非完整词法

• 不解析 C# 11 原始字符串字面量（"""..."""），出现在受保护层会触发误报——避免使用或加 IgnoreFiles
• 病态代码模式（极端嵌套、宏拼接）可能误报
• M8 排期升级到 Roslyn Analyzer 后误报会大幅消失

8.2 规则范围限定

8.3 不会做

• 不检测运行时行为（鉴权链是否真生效、注入是否真发生）——是静态文本扫描
• 不读取 / 修改源码（只读）
• 不联网

九、跑测试 / CI 集成

# 全 sln 测试
dotnet test GJJMicroserviceKit/GJJMicroserviceKit.sln

# 只跑架构守护
dotnet test --filter "FullyQualifiedName~ArchitectureGuardTests"

# 抑制 ANSI（CI 日志友好）
NO_COLOR=1 dotnet test ...

GitHub Actions 片段：

- name: Architecture Guard
  env:
    NO_COLOR: "1"      # CI 不渲染 ANSI
  run: |
    dotnet test GJJ.UniServiceHub/GJJ.UniServiceHub.Tests \
      --filter "FullyQualifiedName~ArchitectureGuardTests" \
      --no-build

十、版本历史