CLI / Codegen

受众：开发者摘要：SpringOpen Devtools CLI 总入口、项目内省命令和 CRUD 全链路预览。

SpringOpen Devtools 提供统一 spring-open CLI 入口。CLI 负责开发者命令发现、项目内省、配置前缀巡检、Controller 路由巡检、迁移文件巡检和 Codegen 预览；Codegen 模块提供 CRUD 全链路预览 contract，用于预览后端 CRUD、迁移、菜单 / 权限、Admin API、Admin 页面、测试骨架和文档片段。

当前命令只输出到标准输出，不直接写入业务模块，便于 Agent 或开发者先检查生成结果再决定是否落盘。

CLI 总入口

bash

./mvnw -pl spring-open-devtools/spring-open-cli -am test -DskipITs -DskipFrontend
java -cp spring-open-devtools/spring-open-cli/target/classes:spring-open-devtools/spring-open-codegen/target/classes \
  com.springopen.devtools.cli.SpringOpenCli list

命令	说明
`spring-open list [--plain]`	列出全部已注册 CLI 命令
`spring-open about`	输出 CLI 版本、当前工作目录、Java / OS、Maven 模块数量、迁移文件数量和命令数量
`spring-open actuator:status [--url <actuator-base-url>] [--timeout <seconds>] [--lifecycle]`	只读请求 Actuator health，可选请求 SpringOpen lifecycle，适合本地启动后的运行态 smoke
`spring-open config:list [--module <artifact-or-path>] [--prefix <prefix>] [--plain]`	扫描源码 `@ConfigurationProperties`，输出配置前缀、Properties 类、Maven 模块和源码路径
`spring-open module:list [--tree]`	从根 `pom.xml` 递归列出 Maven 模块，默认表格，`--tree` 输出树形
`spring-open migrate:list [--owner <owner>] [--type schema\|seed\|delta] [--files]`	扫描源码迁移目录，按 owner 汇总 schema / seed / delta 数量，`--files` 输出具体文件
`spring-open migrate:status [--owner <owner>] [--type schema\|seed\|delta] [--url <jdbc-url>] [--pending\|--applied] [--files]`	解析源码迁移 changeSet；提供 JDBC 连接时读取 `DATABASECHANGELOG` 并标记 applied / pending
`spring-open migrate:run [--owner <owner>] [--type schema\|delta\|all] --url <jdbc-url> --dry-run\|--confirm`	用 Liquibase 执行 schema / delta 迁移；必须显式连接数据库，真实执行必须加 `--confirm`
`spring-open seed:run [--owner <owner>] --url <jdbc-url> --dry-run\|--confirm`	用 Liquibase 执行 seed 迁移；必须显式连接数据库，真实执行必须加 `--confirm`
`spring-open queue:metrics [--url <app-base-url>] [--token <bearer-token>]`	读取运行中应用的 Queue 指标、Worker 状态和积压数量
`spring-open queue:failed [--page <page>] [--size <size>] [--keyword <text>] [--queue <queue>] [--job <job>]`	读取运行中应用的 Queue 失败任务分页
`spring-open queue:retry --id <failed-job-id>`	通过运行中应用重试一个 Queue 失败任务
`spring-open queue:recover`	通过运行中应用恢复超时 PROCESSING 任务
`spring-open queue:work`	明确拒绝在轻量 CLI 进程内直接消费队列，并指引使用应用上下文 Worker
`spring-open route:list [--module <artifact-or-path>] [--method <http-method>] [--path <path-fragment>] [--plain]`	扫描源码 Controller mapping，输出 HTTP 方法、路径、handler、Maven 模块和源码路径
`spring-open schedule:status [--url <app-base-url>] [--token <bearer-token>]`	读取运行中应用的 Scheduler 状态和聚合指标
`spring-open schedule:list [--keyword <text>] [--status <status>] [--failed-only true\|false]`	读取运行中应用的 Scheduler 已注册任务列表
`spring-open schedule:run --task <task-name> --instance <instance-id>`	通过运行中应用手动触发一个 Scheduler 任务实例
`spring-open make:crud ...`	预览 CRUD 后端、Admin、迁移、菜单权限、测试和文档片段
`spring-open version`	输出 CLI 版本
`spring-open help [command]`	输出总帮助或指定命令帮助

CLI 总入口支持 Java ServiceLoader 命令发现。模块可以实现 CliCommandProvider，并用 @AutoService(CliCommandProvider.class) 发布命令贡献；启动时 SpringOpenCli 会按 provider order() 和类名稳定注册命令，重复命令名会 fail-fast，避免两个模块无声覆盖同一命令。

module:list 只读取 Maven pom.xml 的 <modules> 声明，不扫描 target、node_modules、dist、build、.gradle、vendor 等生成物。config:list 只扫描 src/main/java 下的源码 @ConfigurationProperties，会解析常见的字符串字面量、PropertyPrefixes.* 和同类 PREFIX / PROPERTIES_PREFIX 常量拼接，方便排查 starter / core / module 的配置前缀归属。route:list 只扫描 src/main/java 下的 @RestController / @Controller 和 mapping annotation，会解析类级 / 方法级 path 的常见字符串常量拼接；它是源码巡检，不替代 Spring Boot Actuator /actuator/mappings 运行态事实。migrate:list / migrate:status 只扫描 src/main/resources/db/changelog/migrations 下的源码迁移文件，不读取 target/classes。

migrate:status 默认不连接数据库，仅解析源码 XML 中的 <changeSet id author>，用于快速确认 owner / type 范围内有多少变更集。传入 --url <jdbc-url>，或设置 SPRING_OPEN_CLI_DB_URL / SPRING_OPEN_CLI_DB_USERNAME / SPRING_OPEN_CLI_DB_PASSWORD 后，CLI 会通过 JDK DriverManager 查询目标库的 DATABASECHANGELOG，并按 author + id 比对 applied / pending；数据库驱动需由调用方放入 CLI classpath。未连接数据库时禁止使用 --pending / --applied，避免把源码清单误判为真实执行状态。

migrate:run / seed:run 是真实 Liquibase 执行命令，不启动 Spring Boot 应用，但会连接目标数据库并写入 DATABASECHANGELOG。命令必须显式提供 --url 或 SPRING_OPEN_CLI_DB_URL，数据库驱动由调用方放入 CLI classpath；真实执行必须加 --confirm，也可以先用 --dry-run 查看 pending changeSet。CLI 会按源码迁移文件生成临时 master changelog，并把每个 include 的 logicalFilePath 固定为 db/changelog/migrations/<filename>，避免和应用启动时的 classpath 迁移记录发生 filename 漂移。

actuator:status 默认读取 http://localhost:8000/actuator/health；传入 --url 或设置 SPRING_OPEN_ACTUATOR_URL 可改为其他 Actuator base URL。--lifecycle 会额外读取 /actuator/lifecycle，用于确认 SpringOpen 生命周期 manifest / contribution 消费端是否随应用暴露；该命令只读 HTTP，不启动应用、不修改运行态。

queue:* 与 schedule:* 是运行态 HTTP 运维命令，默认访问 http://localhost:8000，传入 --url 或设置 SPRING_OPEN_APP_URL 可切换应用 base URL；传入 --token 或设置 SPRING_OPEN_API_TOKEN 会附加 Authorization: Bearer <token>。这些命令复用已存在的 Admin API：Queue 指标 / 失败任务 / 重试 / 恢复和 Scheduler 状态 / 任务列表 / 手动触发。CLI 不直接连接数据库、不创建 Spring 应用上下文，也不绕过权限；401 / 403 等权限失败会原样显示 HTTP 状态和响应体。

queue:work 不在轻量 CLI 进程里消费队列。Queue Worker 需要 Spring 应用上下文、已注册的 QueueJobHandler Bean、provider 配置以及数据库 / Redis / RabbitMQ 基础设施；消费队列应启动应用并设置 spring.open.queue.worker.enabled=true，再使用 queue:metrics / queue:failed / queue:retry / queue:recover 做运维操作。

CRUD 预览

bash

./mvnw -pl spring-open-devtools/spring-open-codegen -am test -DskipITs -DskipFrontend
java -cp spring-open-devtools/spring-open-codegen/target/classes com.springopen.devtools.codegen.CodegenCli \
  generate crud \
  --module blog \
  --entity BlogArticle \
  --package com.springopen.module.blog \
  --resource-path articles \
  --table blog_article \
  --permission-prefix blog:articles \
  --admin-route /blog/articles \
  --menu-title "Blog Articles"

也可以通过 CLI 总入口调用：

bash

java -cp spring-open-devtools/spring-open-cli/target/classes:spring-open-devtools/spring-open-codegen/target/classes \
  com.springopen.devtools.cli.SpringOpenCli make:crud \
  --module blog \
  --entity BlogArticle \
  --package com.springopen.module.blog

参数：

参数	必填	说明
`--module`	是	业务模块名，用于默认 API 前缀
`--entity`	是	Java 实体名，例如 `BlogArticle`
`--package`	是	生成文件的基础包名
`--resource-path`	否	REST 资源路径片段，默认由实体名转 kebab-case
`--table`	否	数据库表名预览元数据，默认由实体名转 snake_case
`--api-prefix`	否	API 前缀，默认 `/api/v1/<module>`
`--module-root`	否	后端模块根目录，默认 `spring-open-modules/spring-open-module-<module>`
`--permission-prefix`	否	权限前缀，默认 `<module>:<resource-path>`
`--admin-route`	否	后台菜单路由，默认 `/<module>/<resource-path>`
`--menu-title`	否	菜单标题，默认由实体名拆词

当前边界

生成结果是 contract 预览，不自动写文件。
about / config:list / module:list / route:list / migrate:list 是源码内省命令，不启动 Spring Boot 应用，也不连接数据库。
migrate:status 默认也是源码内省；只有显式传入 JDBC 连接时才读取 DATABASECHANGELOG 做 applied / pending 比对，不执行任何 changeSet。
migrate:run / seed:run 会执行 Liquibase changeSet；必须显式连接数据库、显式 --confirm，并保持 DATABASECHANGELOG filename 与应用启动迁移一致。
actuator:status 是运行态只读 smoke，要求应用已启动且 Actuator endpoint 已开放；命令本身不创建 Spring 应用上下文。
queue:* / schedule:* 是运行态 HTTP wrapper，要求应用已启动、对应 Admin API 已装配且当前 token 有权限；它们不在 CLI 进程内消费队列或执行调度逻辑。
migrate:list 只做迁移源码清单和 owner 归属巡检，不替代 Liquibase 真实执行历史；涉及数据库执行状态仍以应用启动和 Liquibase 表为准。
CRUD 模板覆盖 Controller、Service、ServiceImpl、Entity、Mapper、分页 DTO、保存 DTO、更新 DTO 和 VO 首段。
全链路预览会同时输出 Liquibase 建表 / 菜单权限 seed 草稿、Admin API、Admin 页面、Controller / Service 测试骨架和正式文档片段。
Controller 预览包含分页、详情、创建、更新和删除 5 个基础动作。
生成后的真实业务代码仍需按模块规则补齐业务字段、权限挂载、VO 转换、迁移编号、i18n、测试、截图和正式文档；预览中的 0000_00_00_preview_* 文件名不能直接作为生产迁移落盘。
queue:work 当前是边界指引命令，不直接消费队列；如果后续要做单步消费，应优先在运行中应用暴露受权限保护的 Admin API，再由 CLI 作为 HTTP wrapper 调用。

CLI / Codegen ​

CLI 总入口 ​

CRUD 预览 ​

当前边界 ​

CLI / Codegen

CLI 总入口

CRUD 预览

当前边界