test(arch): ArchUnit 规则 1→6 条(强制+棘轮),锁住控制器分层债务

强制:库模块(converter/parity)不得依赖应用编排层 + 模块切片无环。
棘轮(基线化存量、只挡新增):控制器不得新增直用 JdbcTemplate(26)/互相注入(4)/Poc 调试控制器(3)。
架构允许 com.eip4→com.dsasp,故不拦控制器调引擎,只拦直拼原始 SQL。
验证:6/6 绿,临时探针走完整 RED→GREEN 确认棘轮非空绿。见总览 §10 A4。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-06-24 10:36:41 +08:00
parent 850c6501b2
commit ffe89e62bf

View File

@@ -1,21 +1,112 @@
package com.eip4.platform.app;
import com.tngtech.archunit.base.DescribedPredicate;
import com.tngtech.archunit.core.domain.JavaClass;
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.web.bind.annotation.RestController;
import java.util.Set;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;
/**
* 架构纪律(《架构设计》(docs/架构设计.md)第一节,ArchUnit 固化):
* com.eip4.* 可调 com.dsasp.*,反向禁止——保真层不得感知现代层。
* 架构纪律(ArchUnit 编译期固化)。规则分两类:
*
* <p><b>强制规则(hard,当前已绿)</b>:违反即红,守护双层制方向、库模块独立性、模块无环。
*
* <p><b>棘轮规则(ratchet,存量债务基线化)</b>:把现存技术债以「已知债务清单」白名单化,
* 只挡<em>新增</em>违规、不强拆旧代码。清单 = 待偿债务台账,清理一个就从清单删一个,
* 直到清单清空即可把该规则升级为强制规则(删去白名单参数)。
*
* <p>背景、严重度与偿还路线见 {@code docs/项目进度与路线-总览-2026-06-21.md} §10
* (控制器 SQL 收口=A4 / 控制器解耦=A3 / Poc 端点移除=§10.1 P0)。
*
* <p>原则提醒:架构允许 {@code com.eip4.* → com.dsasp.*}(现代层是保真层的薄门面),
* 故「控制器调用保真层引擎服务」<em>不是</em>违规,本测试不拦;真正的坏味道是控制器直拼原始 SQL。
*/
@AnalyzeClasses(packages = {"com.dsasp", "com.eip4"})
@AnalyzeClasses(packages = {"com.dsasp", "com.eip4"}, importOptions = ImportOption.DoNotIncludeTests.class)
class ArchitectureRulesTest {
// ───────────────────────── 强制规则(hard,当前已绿) ─────────────────────────
@ArchTest
static final ArchRule 保真层禁止依赖现代层 =
noClasses().that().resideInAPackage("com.dsasp..")
.should().dependOnClassesThat().resideInAPackage("com.eip4..")
.because("双层制:移植的旧代码不重写、不感知新代码,保证与 framework 源码 diff 最小");
@ArchTest
static final ArchRule 库模块不得依赖应用编排层 =
noClasses().that().resideInAnyPackage("com.eip4.platform.converter..", "com.eip4.platform.parity..")
.should().dependOnClassesThat().resideInAnyPackage(
"com.eip4.platform.metadata..",
"com.eip4.platform.ai..",
"com.eip4.platform.flowgateway..",
"com.eip4.platform.auth..",
"com.eip4.platform.app..")
.because("转换器/对拍是可独立 CLI 跑批的库,不得反向依赖应用编排层(保持可独立运行)");
@ArchTest
static final ArchRule 模块间无循环依赖 =
slices().matching("com.eip4.platform.(*)..").should().beFreeOfCycles()
.because("模块化单体:模块间依赖必须是 DAG,出现环说明模块边界被破坏");
// ───────────────────────── 棘轮规则(ratchet,存量债务基线化) ─────────────────────────
/**
* 控制器直接持有 JdbcTemplate 拼原始 SQL = 现代层退化成第二个「SQL 散落层」的根源(总览 §10 A4)。
* 偿还方向:把 SQL 收口到 Service/Repository 层;清理一个就从本清单删一个。
*/
private static final Set<String> 控制器直用JdbcTemplate_存量债 = Set.of(
"FlowController", "AdminUserController", "TodoController", "ScriptExecuteController",
"EntityController", "PickerController", "PocScriptTestController", "ReportMenuController",
"AdminWriteController", "DesignFeatureController", "OrgController", "ProcessSelectController",
"PocWriteTestController", "AmisSchemaController", "ScheduleJobNotifyController", "TemplateTreeController",
"MetaController", "DataImportConfigController", "MenuController", "UserSelectController",
"EditGridScriptController", "FileController", "PocMasterSubController", "PageSchemaController",
"FieldEditorController", "FormDefaultsController");
@ArchTest
static final ArchRule 控制器不得新增直用JdbcTemplate =
noClasses().that().areAnnotatedWith(RestController.class)
.and(不在债务清单(控制器直用JdbcTemplate_存量债))
.should().dependOnClassesThat().areAssignableTo(JdbcTemplate.class)
.because("控制器应把 SQL 收口到 Service/Repository(总览 §10 A4);存量见清单,新增禁止");
/**
* 控制器互相注入 = 横向耦合,应共同依赖 Service 而非彼此(总览 §10 A3)。
*/
private static final Set<String> 控制器互相依赖_存量债 = Set.of(
"EntityController", "TemplateTreeController", "ScheduleJobNotifyController", "FlowController");
@ArchTest
static final ArchRule 控制器不得新增互相依赖 =
noClasses().that().areAnnotatedWith(RestController.class)
.and(不在债务清单(控制器互相依赖_存量债))
.should().dependOnClassesThat().areAnnotatedWith(RestController.class)
.because("@RestController 之间不得互相注入,应抽公共 Service 切断横向耦合(总览 §10 A3)");
/**
* Poc/调试控制器随生产 jar 装配 = 可达 RCE / 任意 DROP(总览 §10.1 P0)。
* 下列 3 个是<em>待移除</em>的 P0 债,本清单仅为保持构建绿;P0 落地移除后,删清单并把本规则升为强制。
*/
private static final Set<String> Poc控制器_待移除P0 = Set.of(
"PocScriptTestController", "PocWriteTestController", "PocMasterSubController");
@ArchTest
static final ArchRule 不得新增Poc调试控制器 =
classes().that().areAnnotatedWith(RestController.class)
.and(不在债务清单(Poc控制器_待移除P0))
.should().haveSimpleNameNotStartingWith("Poc")
.because("Poc/调试控制器不应进生产装配(总览 §10.1 P0:可达 RCE/任意 DROP);新增禁止,存量待移除");
private static DescribedPredicate<JavaClass> 不在债务清单(Set<String> debt) {
return DescribedPredicate.describe("不在已知债务清单", c -> !debt.contains(c.getSimpleName()));
}
}