cztctl-vscode

VSCode 插件，go-zero 微服务框架扩展代码生成工具 cztctl 的 IDE 插件。支持 .cron（定时任务）和 .rabbitmq（消息队列）DSL 文件的语法高亮、语义着色、语法错误检查、代码导航与代码片段。

配套的 cztctl 代码生成工具 cztctl

使用方法

1. 创建 DSL 文件

在 VSCode 资源管理器中右键文件夹 → 选择 New Cron File (.cron) 或 New RabbitMQ File (.rabbitmq)，输入文件名即可创建带基础结构的 DSL 文件。

2. 编写 DSL

使用 Snippets 快速编写：

• 输入 type → 展开结构体声明
• 输入 server → 展开 @server 注解块
• 输入 service → 展开 service 服务块
• 输入 crontask → 展开完整的定时任务（.cron 文件）
• 输入 consumer → 展开 RabbitMQ 消费者（.rabbitmq 文件）

完整模板列表见下方 Snippets（代码片段） 章节。

3. 生成代码

使用 cztctl CLI 工具从 DSL 文件生成 Go 代码：

# 生成定时任务服务代码
cztctl api cron -api your-service.cron -dir .

# 生成 RabbitMQ 消费者服务代码
cztctl api rabbitmq -api your-service.rabbitmq -dir .

4. 代码导航

• Ctrl+Click（Mac: Cmd+Click）路由参数（如 OrderCancelReq）→ 跳转到对应的 type 定义
• Ctrl+Click import 路径 → 打开引入的文件

功能

语法高亮 + 语义着色

基于 ANTLR4 Lexer/Parser + TextMate Grammar + Semantic Tokens Provider 驱动，覆盖 DSL 全部语法元素，并提供上下文感知的语义配色：

语法错误检查

基于 ANTLR4 Parser 全量解析，实时检测语法错误并以红色波浪线标注：

• 缺少必填声明（syntax / service）
• 括号/大括号不匹配
• 注解格式错误（@cron / @handler / @doc）
• 结构体字段定义错误
• service route 格式错误
• 文件类型语义校验：.rabbitmq 文件中使用 @cron / @cronRetry 会报红线
• 路由分隔符校验：.cron 文件禁止 . 分隔符，.rabbitmq 文件禁止 : 分隔符

代码导航

Ctrl+Click（或 Cmd+Click）跳转：

快速创建文件

右键文件夹 → 上下文菜单：

Snippets（代码片段）

输入缩写后从补全列表选择即可快速展开，共 18 个代码片段：

安装

从 VSIX 安装

1. VSCode → Extensions 侧边栏
2. 点击右上角 ... → Install from VSIX...
3. 选择 cztctl-0.0.1.vsix
4. 重启 VSCode

命令行安装

code --install-extension cztctl-0.0.1.vsix

更新插件

同上步骤，安装新版本 VSIX 即可覆盖旧版本。

构建

前置条件

• Node.js 16+（含 npm）
• Java（用于 antlr4ng-cli 生成 Parser）

构建步骤

cd cztctl-vscode

# 安装依赖
npm install

# 生成 ANTLR4 Parser（仅 .g4 文件变更时需要）
export JAVA_HOME=/path/to/jdk && npm run generate-parser

# 编译 TypeScript
npm run compile

# 打包 VSIX
npx vsce package --allow-missing-repository

构建产物：

cztctl-<version>.vsix

修改版本号

编辑 package.json 中的 version：

"version": "0.0.1"  // 修改为新版本号

项目结构

cztctl-vscode/
├── package.json                       # 插件清单（语言注册/语义Token/Snippets/Commands）
├── tsconfig.json                      # TypeScript 编译配置
├── language-configuration.json        # 括号匹配/注释/自动闭合
├── syntaxes/
│   └── cztctl.tmLanguage.json         # TextMate Grammar（词法级高亮）
├── snippets/
│   └── cztctl.json                    # 18 个代码片段
└── src/
    ├── extension.ts                   # 插件入口（注册所有 Provider）
    ├── parser/
    │   ├── Cztctl.g4                  # ANTLR4 Combined Grammar（词法+语法）
    │   ├── index.ts                   # re-exports
    │   └── generated/                 # antlr4ng-cli 生成的 Lexer/Parser/Listener/Visitor
    ├── highlight/
    │   └── semanticTokens.ts          # Semantic Tokens Provider（17项语义着色）
    ├── diagnostics/
    │   └── validator.ts               # 语法错误诊断 + 4项语义校验
    ├── navigation/
    │   └── definitionProvider.ts      # Ctrl+Click 代码导航（跨文件）
    └── commands/
        └── newFile.ts                 # 右键创建 .cron/.rabbitmq 文件

关键文件说明

技术架构

                    Cztctl.g4
                        │
          ┌─────────────┼─────────────┐
          ▼             ▼             ▼
    CztctlLexer    CztctlParser   CztctlListener
    (generated)    (generated)    (generated)
          │             │             │
          │             │    ┌────────┴────────┐
          │             │    ▼                 ▼
          │             │  semanticTokens.ts  validator.ts
          │             │  (语义着色)         (语法错误+语义校验)
          │             │
          ▼             ▼
  TextMate Grammar   definitionProvider.ts
  (词法级高亮)       (代码导航)

与 cztctl CLI 的关系

本插件与 czt-contrib/cztctl 命令行工具共享同一套语法设计：

三端语法规范保持一致，权威来源为 cztctl CLI 的手写解析器。插件的 Cztctl.g4 需与 CLI 解析器行为对齐。

DSL 语法示例

.cron 文件

syntax = "v1"

info (
    title: "定时任务服务"
    desc: "订单超时自动取消"
)

type OrderCancelReq {
    OrderId int64 `json:"orderId"`
}

@server (
    group: order
)
service order-cron {
    @doc "订单超时取消"
    @cron "*/5 * * * *"
    @cronRetry 3
    @handler OrderCancel
    order-cancel:timeout(OrderCancelReq)
}

.rabbitmq 文件

syntax = "v1"

type PaymentMsg {
    OrderId int64  `json:"orderId"`
    Amount  string `json:"amount"`
}

service payment-mq {
    @doc "支付成功回调"
    @handler PaymentSuccess
    payment.success(PaymentMsg)
}