go stub(ai)

Go 项目调试模式指南

本指南介绍了如何在 Caracal Gateway 项目中使用调试模式，特别是如何利用 Go 的 Build Tags 机制来隔离调试代码。

1. 调试模式原理

我们利用 Go 语言的 Build Tags (构建标签) 机制，在编译阶段决定包含哪些文件。这确保了调试用的代码绝对不会出现在生产环境的二进制文件中。

目前支持的调试特性：

1. disable_jwt: 跳过 API 的 JWT 登录校验。
2. stub_controller: 隔离 Controller 依赖，使用本地 Stub 模拟运行。

2. 跳过 JWT 登录校验 (disable_jwt)

开启此标签后，所有受 jwt() 保护的 API 接口将不再验证 Token，可以直接访问。

• 生产实现: pkg/core/http_jwt.go (!disable_jwt)
• 调试实现: pkg/core/http_jwt_debug.go (disable_jwt)

3. 隔离 Controller (stub_controller)

开启此标签后，Gateway 将不会尝试连接远程 gRPC Controller 服务，而是使用本地 Stub 模拟行为（直接返回成功或阻塞）。这对于没有 Controller 环境的开发非常有用。

• 生产实现: pkg/controller/controller.go (!stub_controller)
• 调试实现: pkg/controller/controller_debug.go (stub_controller)

4. 如何使用

Makefile (推荐)

我们预定义了一个 build-debug 目标，它会自动启用上述所有调试特性，并禁用编译器优化以支持 GDB 调试。

make build-debug

生成的二进制文件位于 bin/caracal-gateway-debug。

手动运行/编译

你可以根据需要组合使用 tags。

只跳过登录:

go run -tags disable_jwt cmd/main.go

只隔离 Controller:

go run -tags stub_controller cmd/main.go

全开 (类似 make build-debug):

go run -tags "disable_jwt stub_controller" cmd/main.go

VS Code 配置

在 .vscode/launch.json 中添加配置：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch (Debug Mode)",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${workspaceFolder}/cmd/main.go",
            "buildFlags": "-tags \"disable_jwt stub_controller\""
        }
    ]
}