[每周一更]-(第100期)：介绍 goctl自动生成代码

​ 在自己组件库中，由于部分设计会存在重复引用各个模板的文件，并且基础架构中需要基础模块内容，就想到自动生成代码模板，刚好之前有使用过goctl，以下就简单描述下gozero中goctl场景和逻辑，后续自己借鉴将自己的自动生产逻辑完成再分享。

​ gozero 是一个支持微服务的 Golang Web 和 RPC 框架，它提供了一套工具用于快速生成代码。其中，goctl 是 GoZero 的一个重要工具，用于根据 API 定义文件自动生成代码。理解 goctl 自动生成代码模块的逻辑，有助于开发者快速上手并有效使用 GoZero 框架。

gozero 和 goctl 介绍

• gozero：是一个基于 Go 语言的微服务框架，提供了 Web 和 RPC 支持，旨在提高开发效率并简化微服务架构的开发和维护。
• goctl：是 GoZero 提供的一个命令行工具，用于根据定义文件自动生成代码，包括 API 接口、数据模型、服务逻辑等，goctl 也可以是 go-zero 的内置脚手架，是提升开发效率的一大利器，可以一键生成代码、文档、部署 k8s yaml、dockerfile 等。

goctl 自动生成代码的逻辑

goctl 的工作流程大致分为以下几个步骤：

1. 定义 API 文件：开发者编写一个 .api 文件，描述 API 的接口、请求和响应参数。
2. 解析 API 文件：goctl 读取并解析 .api 文件，将其转换为内部的数据结构。
3. 生成代码模板：根据解析后的数据结构，goctl 应用代码模板生成各类代码文件。
4. 生成文件：将生成的代码模板输出到指定的目录中，供开发者使用和扩展。

详细步骤

1. 定义 API 文件

API 文件使用特定的语法描述服务接口。例如：

syntax = "v1"info(title: "User Service"description: "Service for user management"
)type (UserRequest {Name string `json:"name"`Age  int    `json:"age"`}UserResponse {Id   int    `json:"id"`Name string `json:"name"`}
)service user-api {@handler CreateUserpost /users (UserRequest) returns (UserResponse)
}

2. 解析 API 文件

goctl 读取 .api 文件并解析其内容，转换为内部的数据结构。解析器会识别文件中的语法，并将接口、请求和响应参数等信息提取出来。

3. 生成代码模板

解析后的数据结构会传递给代码生成器，代码生成器会使用预定义的模板生成代码。GoZero 使用 template 包或其他模板引擎来生成代码文件。例如，生成处理器代码、数据模型、路由配置等。

4. 生成文件

最终，生成的代码模板会输出到指定的目录中。例如，生成的代码文件可能包括：

• handler 文件：包含处理请求的逻辑。
• model 文件：包含数据模型定义。
• router 文件：配置路由信息。

示例：使用 goctl 生成代码

假设我们有一个 user.api 文件，内容如下：

syntax = "v1"info(title: "User Service"description: "Service for user management"
)type (UserRequest {Name string `json:"name"`Age  int    `json:"age"`}UserResponse {Id   int    `json:"id"`Name string `json:"name"`}
)service user-api {@handler CreateUserpost /users (UserRequest) returns (UserResponse)
}

使用 goctl 命令生成代码：

goctl api go -api user.api -dir .

命令说明：

• goctl api go：指定生成 Go 语言代码。
• -api user.api：指定 API 文件。
• -dir .：指定生成代码的输出目录。

生成的目录结构可能如下：

.
├── etc
│   └── user-api.yaml
├── user
│   ├── user.go
│   ├── userhandler.go
│   ├── userlogic.go
│   ├── usermodel.go
│   └── userservice.go
└── user-api.go

生成代码文件解释

• user.go：主服务入口文件。
• userhandler.go：包含 CreateUser 处理器的代码。
• userlogic.go：包含业务逻辑处理的代码。
• usermodel.go：包含数据模型的定义。
• userservice.go：包含服务层的代码。
• user-api.go：API 服务的初始化代码。

示例生成 API 服务

以下是一个简单的示例，演示如何使用 goctl 生成一个 API 服务：

API 描述文件（example.api）

info:title: Example APIversion: 1.0.0desc: This is an example APItypes:UserRequest {Name string `json:"name"`Age  int    `json:"age"`}UserResponse {ID   int    `json:"id"`Name string `json:"name"`Age  int    `json:"age"`}service:- getUserget /user/{id}returns (UserResponse)- createUserpost /userrequest (UserRequest)returns (UserResponse)

使用 goctl 生成代码

运行以下命令，使用 goctl 根据 API 描述文件生成代码：

bash
复制代码
goctl api go -api example.api -dir .

生成的目录结构

plaintext
复制代码
.
├── etc
│   └── example-api.yaml
├── internal
│   ├── config
│   │   └── config.go
│   ├── handler
│   │   ├── createuserhandler.go
│   │   └── getuserhandler.go
│   ├── logic
│   │   ├── createuserlogic.go
│   │   └── getuserlogic.go
│   ├── svc
│   │   └── servicecontext.go
│   └── types
│       └── types.go
├── example.api
└── example.go

代码逻辑

1. API 描述文件解析：
   • goctl 读取 example.api 文件，解析出 getUser 和 createUser 两个接口，以及 UserRequest 和 UserResponse 数据类型。
2. 生成配置文件：
   • etc/example-api.yaml：用于存放服务配置，例如服务端口、数据库连接等信息。
3. 生成代码文件：
   • internal/config/config.go：用于加载和管理配置文件。
   • internal/handler：存放 HTTP 请求处理逻辑，每个接口对应一个处理函数。
   • internal/logic：存放具体的业务逻辑，每个接口对应一个逻辑处理函数。
   • internal/svc/servicecontext.go：用于初始化服务的上下文，管理服务依赖。
   • internal/types/types.go：定义请求和响应的数据类型。

优势

• 自动化：通过描述文件自动生成代码，大大减少了手工编码的工作量。
• 规范化：生成的代码符合 go-zero 框架的最佳实践，确保代码风格一致，结构清晰。
• 高效：快速生成 API 服务，提高开发效率。

参考

• api-demo
• 微服务效率工具 goctl 深度解析（上）
• goctl-api