arch-clean

arch-clean

用途

此技能在代码库中实现整洁架构原则，重点关注使用端口/适配器、依赖倒置、用例、实体和可测试性的六边形架构模式。它会重构或生成代码，以强制分离关注点，让系统更模块化、更易于测试。

适用场景

在重构单体应用以提升可维护性、启动对可测试性要求较高的新项目，或在不紧密耦合的情况下集成外部依赖时使用此技能。可将其用于业务逻辑复杂的场景，例如电子商务后端；也可在将遗留代码改造为微服务等现代架构时使用。

主要功能

• 为适配器生成端口接口，确保依赖倒置（例如定义 interface UserPort { fetchUser(id: string): User; } 这样的契约）。
• 创建协调实体和端口的用例类，促进单一职责原则。
• 通过将外部库封装在适配器中来倒置依赖，例如将直接数据库调用转换为端口实现。
• 通过将代码组织为便于单元测试的结构来确保可测试性，例如在用例中模拟端口。
• 验证架构规则，例如通过静态分析检查内层是否依赖外层。

使用模式

通过 OpenClaw 的 CLI 快速重构，或通过 API 用于自动化流水线。先使用扫描命令分析代码库，再应用转换。编写脚本时，将输出传递给 Make 或 Gradle 等构建工具。务必指定目标目录和语言（例如 TypeScript 或 Java），以免使用默认值。在 CI/CD 中，可将其用于提交前钩子以强制执行架构规则。

常用命令/API

使用 OpenClaw CLI 时，子命令以 arch-clean 为前缀。身份验证需要将 $OPENCLAW_API_KEY 设置为环境变量。

• 生成端口接口：

  openclaw arch-clean generate-port --name UserPort --methods "fetchUser(id: string)" --lang ts
  

  这会创建类似 UserPort.ts 的文件，其中包含该接口。

• 在模块中倒置依赖：

  openclaw arch-clean invert-dep --path src/services --adapter DatabaseAdapter
  

  扫描指定路径并封装依赖，例如将直接导入替换为适配器调用。

• 创建用例：

  openclaw arch-clean create-usecase --name FetchUser --ports UserPort --entities User
  

  生成类似 FetchUserUseCase.ts 的类，并注入端口。

以编程方式使用的 API 端点：

• POST /api/arch-clean/generate：请求体为 { "type": "port", "name": "UserPort", "methods": ["fetchUser(id: string)"] }，请求头中需要包含 $OPENCLAW_API_KEY。
• PUT /api/arch-clean/invert：请求体为 { "path": "src/services", "adapter": "DatabaseAdapter" }。

配置格式：使用 JSON 文件定义自定义规则，例如在 .openclaw-arch.json 中配置 { "layers": { "domain": ["entities", "usecases"], "adapters": ["http", "db"] } }。

集成说明

在项目中添加 OpenClaw 作为依赖即可集成（例如运行 npm install openclaw 或使用 Docker 镜像）。设置 $OPENCLAW_API_KEY 以发送经过身份验证的请求。对于 IDE 插件，可通过类似 { "arch-clean": { "defaultLang": "ts", "excludePaths": ["tests/**"] } } 的设置进行配置。可通过传递输出等方式与 ESLint 等代码检查工具结合使用，例如 openclaw arch-clean scan | eslint --fix。确保代码库采用受支持的结构，例如使用 "domain"、"application" 和 "infrastructure" 文件夹，以符合六边形架构模式。

错误处理

检查命令输出中的错误；CLI 会返回非零退出码和 JSON 错误消息，例如 { "error": "Dependency not inverted: invalid path" }。对于 API，预期会收到 HTTP 4xx/5xx 响应，响应体类似 { "code": 400, "message": "Missing required field: methods" }。可使用 try-catch 块处理，例如：

try {
  const response = await fetch('/api/arch-clean/generate', { headers: { 'X-API-Key': process.env.OPENCLAW_API_KEY } });
  if (!response.ok) throw new Error(response.statusText);
} catch (error) {
  console.error('Arch error:', error.message);
}

对于临时性错误（例如网络问题），最多重试 3 次，并使用指数退避。

使用示例

1. 重构简单服务以使用端口： 对于 Node.js 应用，运行 openclaw arch-clean invert-dep --path src/userService.js --adapter HttpAdapter。这会将直接的 HTTP 调用转换为端口，例如，将 axios.get('/user') 改为 this.userPort.fetchUser(id)，从而允许使用模拟对象，提高可测试性。

2. 为业务逻辑生成用例： 在 Java 项目中，执行 openclaw arch-clean create-usecase --name OrderProcessor --ports PaymentPort --entities Order。这会生成 OrderProcessor.java，其中包含类似 public void process(Order order) { this.paymentPort.charge(order); } 的方法，从而通过依赖注入实现更好的架构。

图关系

• 相关：se-architecture 集群（例如，链接到 code-refactor 等技能，以进行更广泛的重构）。
• 依赖：ports-adapters 标签（关联到 hexagonal-architecture，以实现适配器）。
• 冲突：单体模式（避免遗留系统中的紧密耦合）。