1899 lines
53 KiB
Markdown
1899 lines
53 KiB
Markdown
# KRA AutoCode 自动代码生成工具
|
||
|
||
KRA AutoCode 是一个强大的代码生成工具，支持生成符合 Kratos DDD 架构的后端代码和 React TypeScript 前端代码。
|
||
|
||
## 目录
|
||
|
||
- [功能特性](#功能特性)
|
||
- [快速开始](#快速开始)
|
||
- [CLI 命令说明](#cli-命令说明)
|
||
- [配置文件格式](#配置文件格式)
|
||
- [Web 界面使用](#web-界面使用)
|
||
- [模板自定义](#模板自定义)
|
||
- [生成的代码结构](#生成的代码结构)
|
||
- [常见问题](#常见问题)
|
||
|
||
## 功能特性
|
||
|
||
- **Kratos DDD 架构**: 生成符合 Kratos 分层架构的代码（biz/data/service/server）
|
||
- **GORM Gen 集成**: 使用 GORM Gen 生成类型安全的数据库操作代码
|
||
- **React TypeScript**: 生成现代化的 React 前端代码，使用 Ant Design Pro 组件
|
||
- **双入口支持**: 同时支持 CLI 命令行和 Web 界面两种生成方式
|
||
- **多数据库支持**: 支持 MySQL、PostgreSQL、SQLite 数据库
|
||
- **代码注入**: 自动注入 Wire Provider、路由注册等代码
|
||
- **历史记录**: 支持生成历史记录和代码回滚
|
||
|
||
## 快速开始
|
||
|
||
### 方式一：使用 CLI 工具
|
||
|
||
```bash
|
||
# 从配置文件生成代码
|
||
kra-gen generate -c autocode.yaml
|
||
|
||
# 交互模式（推荐新手使用）
|
||
kra-gen generate -i
|
||
|
||
# 预览模式（不写入文件）
|
||
kra-gen generate -c autocode.yaml -p
|
||
```
|
||
|
||
### 方式二：使用 Web 界面
|
||
|
||
1. 启动 KRA 服务
|
||
2. 访问 `系统工具 > 代码生成器`
|
||
3. 选择数据库和表
|
||
4. 配置字段选项
|
||
5. 预览并生成代码
|
||
|
||
## CLI 命令说明
|
||
|
||
KRA 代码生成工具提供了完整的命令行接口，支持配置文件、命令行参数和交互模式三种方式进行代码生成。
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
# 从源码编译
|
||
go build -o kra-gen ./cmd/kra-gen
|
||
|
||
# 或者使用 go install
|
||
go install ./cmd/kra-gen
|
||
```
|
||
|
||
### 基础命令
|
||
|
||
```bash
|
||
kra-gen [command] [flags]
|
||
```
|
||
|
||
### 全局参数
|
||
|
||
以下参数可用于所有子命令：
|
||
|
||
| 参数 | 简写 | 说明 | 默认值 |
|
||
|------|------|------|--------|
|
||
| `--config` | `-c` | 配置文件路径 (YAML/JSON) | - |
|
||
| `--output` | `-o` | 输出目录 | 当前项目目录 |
|
||
| `--template` | `-t` | 模板目录 | resource/package |
|
||
| `--verbose` | `-v` | 显示详细输出 | false |
|
||
| `--help` | `-h` | 显示帮助信息 | - |
|
||
|
||
### 可用命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `generate` | 生成代码（核心命令） |
|
||
| `preview` | 预览生成的代码（不写入文件） |
|
||
| `list` | 列出可用资源（模板、包、数据库） |
|
||
| `version` | 显示版本信息 |
|
||
| `help` | 显示帮助信息 |
|
||
|
||
---
|
||
|
||
### generate 命令
|
||
|
||
生成 Kratos DDD 架构的后端代码和 React 前端代码。这是 CLI 工具的核心命令。
|
||
|
||
```bash
|
||
kra-gen generate [flags]
|
||
```
|
||
|
||
#### 参数说明
|
||
|
||
| 参数 | 简写 | 说明 | 默认值 |
|
||
|------|------|------|--------|
|
||
| `--config` | `-c` | 配置文件路径 (YAML/JSON) | - |
|
||
| `--interactive` | `-i` | 交互模式（推荐新手使用） | false |
|
||
| `--preview` | `-p` | 预览模式（不写入文件） | false |
|
||
| `--output` | `-o` | 输出目录 | 当前目录 |
|
||
| `--template` | `-t` | 模板目录 | resource/package |
|
||
| `--db` | - | 数据库连接名 | - |
|
||
| `--table` | - | 表名 | - |
|
||
| `--package` | - | 包名 | - |
|
||
| `--struct` | - | 结构体名 | - |
|
||
| `--desc` | - | 描述 | - |
|
||
| `--no-web` | - | 不生成前端代码 | false |
|
||
| `--no-server` | - | 不生成后端代码 | false |
|
||
| `--only-template` | - | 仅生成模板（不注入代码） | false |
|
||
| `--add` | - | 追加模式（不覆盖已有文件） | false |
|
||
| `--tree` | - | 树形结构数据 | false |
|
||
| `--tree-json` | - | 树形结构展示字段 | - |
|
||
| `--verbose` | `-v` | 显示详细输出 | false |
|
||
|
||
#### 三种使用方式
|
||
|
||
**方式一：配置文件方式（推荐用于复杂配置）**
|
||
|
||
```bash
|
||
# 使用 YAML 配置文件
|
||
kra-gen generate -c autocode.yaml
|
||
|
||
# 使用 JSON 配置文件
|
||
kra-gen generate -c autocode.json
|
||
```
|
||
|
||
**方式二：命令行参数方式（适合简单场景）**
|
||
|
||
```bash
|
||
# 基本用法
|
||
kra-gen generate --table users --package example --struct User
|
||
|
||
# 完整参数
|
||
kra-gen generate \
|
||
--db mysql \
|
||
--table users \
|
||
--package example \
|
||
--struct User \
|
||
--desc "用户管理"
|
||
```
|
||
|
||
**方式三：交互模式（推荐新手使用）**
|
||
|
||
```bash
|
||
kra-gen generate -i
|
||
```
|
||
|
||
交互模式会引导你完成以下步骤：
|
||
1. 配置数据库连接（支持从 configs/config.yaml 自动读取）
|
||
2. 选择数据库
|
||
3. 选择数据表
|
||
4. 配置基本信息（结构体名、包名、描述等）
|
||
5. 配置字段（显示、验证、搜索、关联等）
|
||
6. 配置生成选项
|
||
|
||
#### 使用示例
|
||
|
||
```bash
|
||
# 从配置文件生成
|
||
kra-gen generate -c autocode.yaml
|
||
|
||
# 使用命令行参数
|
||
kra-gen generate --db mysql --table users --package example --struct User --desc "用户管理"
|
||
|
||
# 交互模式
|
||
kra-gen generate -i
|
||
|
||
# 预览模式（不写入文件）
|
||
kra-gen generate -c autocode.yaml -p
|
||
|
||
# 仅生成后端代码
|
||
kra-gen generate -c autocode.yaml --no-web
|
||
|
||
# 仅生成前端代码
|
||
kra-gen generate -c autocode.yaml --no-server
|
||
|
||
# 仅生成模板（不注入代码到现有文件）
|
||
kra-gen generate -c autocode.yaml --only-template
|
||
|
||
# 追加模式（不覆盖已有文件）
|
||
kra-gen generate -c autocode.yaml --add
|
||
|
||
# 树形结构数据
|
||
kra-gen generate -c autocode.yaml --tree --tree-json name
|
||
|
||
# 详细输出模式
|
||
kra-gen generate -c autocode.yaml -v
|
||
|
||
# 指定输出目录
|
||
kra-gen generate -c autocode.yaml -o /path/to/project
|
||
|
||
# 使用自定义模板
|
||
kra-gen generate -c autocode.yaml -t /path/to/custom/templates
|
||
```
|
||
|
||
#### 交互模式详细流程
|
||
|
||
交互模式提供了完整的引导式配置体验：
|
||
|
||
```
|
||
========================================
|
||
KRA 代码生成 - 交互模式
|
||
========================================
|
||
|
||
步骤 1/6: 配置数据库连接
|
||
----------------------------------------
|
||
检测到配置文件: configs/config.yaml
|
||
是否使用配置文件中的数据库连接? (y/n): y
|
||
使用 MySQL 数据库: root@127.0.0.1:3306/kra
|
||
正在连接数据库... 成功!
|
||
|
||
步骤 2/6: 选择数据库
|
||
----------------------------------------
|
||
可用数据库:
|
||
1. information_schema
|
||
2. kra (当前)
|
||
3. mysql
|
||
请选择数据库 [2]: 2
|
||
已选择数据库: kra
|
||
|
||
步骤 3/6: 选择数据表
|
||
----------------------------------------
|
||
数据库 kra 中的表:
|
||
1. sys_users
|
||
2. sys_apis
|
||
3. articles
|
||
请选择表 (输入序号): 3
|
||
已选择表: articles
|
||
|
||
步骤 4/6: 配置基本信息
|
||
----------------------------------------
|
||
结构体名称 [Articles]: Article
|
||
包名 [articles]: example
|
||
缩写 [article]: article
|
||
功能描述 [Article管理]: 文章管理
|
||
|
||
步骤 5/6: 配置字段
|
||
----------------------------------------
|
||
表 articles 的字段:
|
||
----------------------------------------
|
||
[跳过] id (系统字段)
|
||
[跳过] created_at (系统字段)
|
||
[跳过] updated_at (系统字段)
|
||
[跳过] deleted_at (系统字段)
|
||
Title (string) - 标题
|
||
Content (string) - 内容
|
||
Status (int) - 状态
|
||
----------------------------------------
|
||
共 3 个字段
|
||
是否需要详细配置每个字段? (y/n): y
|
||
|
||
步骤 6/6: 配置生成选项
|
||
----------------------------------------
|
||
【基础配置】
|
||
使用 KRA_MODEL (包含 ID, CreatedAt, UpdatedAt, DeletedAt)? (y/n) [y]: y
|
||
自动迁移数据库表结构? (y/n) [y]: y
|
||
|
||
【生成范围】
|
||
生成后端代码? (y/n) [y]: y
|
||
生成前端代码? (y/n) [y]: y
|
||
|
||
【高级选项】
|
||
仅生成模板 (不注入代码到现有文件)? (y/n) [n]: n
|
||
追加模式 (不覆盖已有文件)? (y/n) [n]: n
|
||
|
||
【自动注册配置】
|
||
自动创建 API 记录? (y/n) [y]: y
|
||
自动创建菜单记录? (y/n) [y]: y
|
||
自动创建按钮权限? (y/n) [y]: y
|
||
自动创建资源标识? (y/n) [n]: n
|
||
|
||
【树形结构配置】
|
||
是否为树形结构数据? (y/n): n
|
||
|
||
========================================
|
||
配置完成!
|
||
========================================
|
||
```
|
||
|
||
---
|
||
|
||
### preview 命令
|
||
|
||
预览将要生成的代码，不写入任何文件。这是 `generate -p` 的快捷方式，但提供了更多预览选项。
|
||
|
||
```bash
|
||
kra-gen preview [flags]
|
||
```
|
||
|
||
#### 参数说明
|
||
|
||
| 参数 | 简写 | 说明 | 默认值 |
|
||
|------|------|------|--------|
|
||
| `--config` | `-c` | 配置文件路径 | - |
|
||
| `--db` | - | 数据库连接名 | - |
|
||
| `--table` | - | 表名 | - |
|
||
| `--package` | - | 包名 | - |
|
||
| `--struct` | - | 结构体名 | - |
|
||
| `--desc` | - | 描述 | - |
|
||
| `--no-web` | - | 不生成前端代码 | false |
|
||
| `--no-server` | - | 不生成后端代码 | false |
|
||
| `--full` | - | 显示完整代码内容（带语法高亮） | false |
|
||
| `--no-color` | - | 不使用语法高亮 | false |
|
||
|
||
#### 使用示例
|
||
|
||
```bash
|
||
# 简单预览（显示文件列表和配置摘要）
|
||
kra-gen preview -c autocode.yaml
|
||
|
||
# 完整预览（显示所有生成的代码内容）
|
||
kra-gen preview -c autocode.yaml --full
|
||
|
||
# 完整预览，不使用语法高亮（适合重定向到文件）
|
||
kra-gen preview -c autocode.yaml --full --no-color
|
||
|
||
# 仅预览后端代码
|
||
kra-gen preview -c autocode.yaml --full --no-web
|
||
|
||
# 仅预览前端代码
|
||
kra-gen preview -c autocode.yaml --full --no-server
|
||
|
||
# 使用命令行参数预览
|
||
kra-gen preview --table users --package example --struct User
|
||
```
|
||
|
||
#### 预览输出示例
|
||
|
||
**简单预览模式：**
|
||
|
||
```
|
||
========================================
|
||
代码预览模式
|
||
========================================
|
||
包名: example
|
||
结构体: Article
|
||
表名: articles
|
||
描述: 文章管理
|
||
数据库: kra
|
||
----------------------------------------
|
||
生成选项:
|
||
使用 KRA_MODEL: 是
|
||
自动迁移: 是
|
||
生成后端: 是
|
||
生成前端: 是
|
||
仅生成模板: 否
|
||
追加模式: 否
|
||
创建 API 记录: 是
|
||
创建菜单记录: 是
|
||
创建按钮权限: 是
|
||
创建资源标识: 否
|
||
----------------------------------------
|
||
将生成以下文件:
|
||
|
||
后端文件:
|
||
- ./internal/biz/example/article.go
|
||
- ./internal/data/example/article.go
|
||
- ./internal/data/model/example/article.go
|
||
- ./internal/service/example/article.go
|
||
- ./internal/service/types/example/request/article.go
|
||
- ./internal/server/handler/example/article.go
|
||
- ./internal/server/router/example/article.go
|
||
|
||
前端文件:
|
||
- ./web/src/pages/example/article/index.tsx
|
||
- ./web/src/pages/example/article/form.tsx
|
||
- ./web/src/pages/example/article/detail.tsx
|
||
- ./web/src/services/kratos/example.ts
|
||
- ./web/src/types/example/article.d.ts
|
||
|
||
字段配置:
|
||
- Title (string): 标题 [搜索:LIKE]
|
||
- Content (string): 内容
|
||
- Status (int): 状态 [搜索:EQ] [字典:article_status]
|
||
|
||
========================================
|
||
预览完成，未写入任何文件
|
||
========================================
|
||
```
|
||
|
||
**完整预览模式（--full）：**
|
||
|
||
```
|
||
╔════════════════════════════════════════════════════════════════╗
|
||
║ KRA 代码预览 (完整模式) ║
|
||
╚════════════════════════════════════════════════════════════════╝
|
||
|
||
包名: example
|
||
结构体: Article
|
||
表名: articles
|
||
描述: 文章管理
|
||
|
||
────────────────────────────────────────────────────────────────
|
||
📄 Biz Layer
|
||
输出路径: ./internal/biz/example/article.go
|
||
|
||
1 │ package example
|
||
2 │
|
||
3 │ import (
|
||
4 │ "context"
|
||
5 │ "github.com/go-kratos/kratos/v2/log"
|
||
6 │ )
|
||
7 │
|
||
8 │ // ArticleRepo 仓储接口
|
||
9 │ type ArticleRepo interface {
|
||
10 │ Create(ctx context.Context, article *Article) error
|
||
...
|
||
|
||
════════════════════════════════════════════════════════════════
|
||
预览统计
|
||
成功: 12 个文件
|
||
|
||
⚠️ 预览模式 - 未写入任何文件
|
||
```
|
||
|
||
---
|
||
|
||
### list 命令
|
||
|
||
列出可用的模板、包或数据库连接。
|
||
|
||
```bash
|
||
kra-gen list [templates|packages|databases]
|
||
```
|
||
|
||
#### 子命令说明
|
||
|
||
| 子命令 | 说明 |
|
||
|--------|------|
|
||
| `templates` | 列出可用的代码生成模板 |
|
||
| `packages` | 列出已创建的业务包 |
|
||
| `databases` | 列出配置的数据库连接 |
|
||
|
||
#### 使用示例
|
||
|
||
```bash
|
||
# 列出可用模板
|
||
kra-gen list templates
|
||
|
||
# 输出:
|
||
# 可用模板:
|
||
# package - 标准包模板 (Kratos DDD 架构)
|
||
# plugin - 插件模板 (独立功能模块)
|
||
|
||
# 列出已创建的包
|
||
kra-gen list packages
|
||
|
||
# 输出:
|
||
# 已创建的包:
|
||
# (需要连接数据库获取)
|
||
|
||
# 列出数据库连接
|
||
kra-gen list databases
|
||
|
||
# 输出:
|
||
# 数据库连接:
|
||
# MySQL: root@127.0.0.1:3306/kra
|
||
```
|
||
|
||
---
|
||
|
||
### version 命令
|
||
|
||
显示 KRA 代码生成工具的版本信息。
|
||
|
||
```bash
|
||
kra-gen version
|
||
```
|
||
|
||
#### 输出示例
|
||
|
||
```
|
||
kra-gen v1.0.0
|
||
KRA 自动代码生成工具
|
||
支持 Kratos DDD 架构 + GORM Gen + React TypeScript
|
||
```
|
||
|
||
---
|
||
|
||
### 退出码
|
||
|
||
| 退出码 | 说明 |
|
||
|--------|------|
|
||
| 0 | 成功 |
|
||
| 1 | 一般错误（配置错误、验证失败等） |
|
||
|
||
---
|
||
|
||
### 环境变量
|
||
|
||
| 变量名 | 说明 | 默认值 |
|
||
|--------|------|--------|
|
||
| `KRA_CONFIG` | 默认配置文件路径 | - |
|
||
| `KRA_TEMPLATE_DIR` | 默认模板目录 | resource/package |
|
||
| `KRA_OUTPUT_DIR` | 默认输出目录 | 当前目录 |
|
||
|
||
---
|
||
|
||
### 常用命令组合
|
||
|
||
```bash
|
||
# 快速生成（使用配置文件）
|
||
kra-gen generate -c autocode.yaml
|
||
|
||
# 新手入门（交互模式）
|
||
kra-gen generate -i
|
||
|
||
# 预览后生成
|
||
kra-gen preview -c autocode.yaml --full && kra-gen generate -c autocode.yaml
|
||
|
||
# 仅生成后端代码
|
||
kra-gen generate -c autocode.yaml --no-web
|
||
|
||
# 仅生成前端代码
|
||
kra-gen generate -c autocode.yaml --no-server
|
||
|
||
# 安全生成（追加模式，不覆盖已有文件）
|
||
kra-gen generate -c autocode.yaml --add
|
||
|
||
# 模板开发（仅生成模板，不注入代码）
|
||
kra-gen generate -c autocode.yaml --only-template
|
||
|
||
# 树形结构数据
|
||
kra-gen generate -c autocode.yaml --tree --tree-json name
|
||
|
||
# 使用自定义模板
|
||
kra-gen generate -c autocode.yaml -t /path/to/custom/templates
|
||
|
||
# 详细输出（调试用）
|
||
kra-gen generate -c autocode.yaml -v
|
||
```
|
||
|
||
## 配置文件格式
|
||
|
||
配置文件支持 YAML 和 JSON 两种格式，推荐使用 YAML 格式（更易读）。
|
||
|
||
### 配置文件结构概览
|
||
|
||
```
|
||
配置文件
|
||
├── 基础信息 # package, structName, tableName 等
|
||
├── 生成选项 (options) # gvaModel, autoMigrate, generateWeb 等
|
||
├── 字段配置 (fields) # 字段列表，每个字段包含类型、显示、搜索等配置
|
||
└── 自定义方法 (customMethods) # 可选，用于生成自定义查询方法
|
||
```
|
||
|
||
### YAML 格式完整示例
|
||
|
||
```yaml
|
||
# autocode.yaml
|
||
|
||
# ==================== 基础信息 ====================
|
||
package: example # 包名（小写，用于目录和包名）
|
||
structName: Article # 结构体名称（大驼峰，用于 Go 结构体）
|
||
tableName: articles # 数据库表名（下划线命名）
|
||
description: 文章管理 # 功能描述（用于注释和文档）
|
||
businessDB: "" # 业务数据库（空表示默认数据库）
|
||
abbreviation: article # 缩写（用于路由前缀和变量名）
|
||
|
||
# ==================== 生成选项 ====================
|
||
options:
|
||
# --- 基础配置 ---
|
||
gvaModel: true # 使用 KRA_MODEL（包含 ID, CreatedAt, UpdatedAt, DeletedAt）
|
||
autoMigrate: true # 自动迁移数据库表结构
|
||
|
||
# --- 生成范围 ---
|
||
generateWeb: true # 生成前端代码
|
||
generateServer: true # 生成后端代码
|
||
|
||
# --- 高级选项 ---
|
||
onlyTemplate: false # 仅生成模板（不注入代码到现有文件）
|
||
isAdd: false # 追加模式（不覆盖已有文件）
|
||
|
||
# --- 自动注册配置（仅在 onlyTemplate=false 时生效）---
|
||
autoCreateApiToSql: true # 自动创建 API 记录到 sys_apis 表
|
||
autoCreateMenuToSql: true # 自动创建菜单记录到 sys_base_menus 表
|
||
autoCreateBtnAuth: true # 自动创建按钮权限
|
||
autoCreateResource: false # 自动创建资源标识
|
||
|
||
# --- 树形结构配置 ---
|
||
isTree: false # 是否为树形结构数据
|
||
treeJson: "" # 树形结构展示字段（如: name, title）
|
||
|
||
# ==================== 字段配置 ====================
|
||
fields:
|
||
# --- 字符串字段示例 ---
|
||
- fieldName: Title # Go 字段名（大驼峰）
|
||
fieldDesc: 标题 # 字段描述/注释
|
||
fieldType: string # Go 类型
|
||
fieldJson: title # JSON 字段名（小驼峰）
|
||
columnName: title # 数据库列名（下划线）
|
||
dataTypeLong: varchar(255) # 数据库类型
|
||
form: true # 显示在表单中
|
||
table: true # 显示在表格中
|
||
desc: true # 显示在详情页
|
||
excel: true # 支持导入/导出
|
||
require: true # 是否必填
|
||
errorText: 请输入标题 # 校验失败提示
|
||
clearable: true # 是否可清空
|
||
sort: false # 是否支持排序
|
||
fieldSearchType: LIKE # 搜索类型
|
||
fieldSearchHide: false # 是否隐藏搜索条件
|
||
fieldIndexType: "" # 索引类型
|
||
|
||
# --- 文本字段示例 ---
|
||
- fieldName: Content
|
||
fieldDesc: 内容
|
||
fieldType: string
|
||
fieldJson: content
|
||
columnName: content
|
||
dataTypeLong: text
|
||
form: true
|
||
table: false # 长文本不在表格中显示
|
||
desc: true
|
||
excel: false
|
||
require: false
|
||
clearable: true
|
||
|
||
# --- 带字典的字段示例 ---
|
||
- fieldName: Status
|
||
fieldDesc: 状态
|
||
fieldType: int
|
||
fieldJson: status
|
||
columnName: status
|
||
dataTypeLong: tinyint(1)
|
||
form: true
|
||
table: true
|
||
desc: true
|
||
require: false
|
||
defaultValue: "1" # 默认值
|
||
fieldSearchType: EQ # 精确匹配
|
||
dictType: article_status # 字典类型（用于下拉选择）
|
||
|
||
# --- 带数据源的字段示例 ---
|
||
- fieldName: AuthorID
|
||
fieldDesc: 作者ID
|
||
fieldType: uint
|
||
fieldJson: authorId
|
||
columnName: author_id
|
||
dataTypeLong: bigint(20)
|
||
form: true
|
||
table: true
|
||
require: true
|
||
fieldSearchType: EQ
|
||
fieldIndexType: index # 普通索引
|
||
dataSource: # 数据源配置
|
||
dbName: "" # 数据库名（空表示当前数据库）
|
||
table: sys_users # 关联表名
|
||
label: nick_name # 显示字段
|
||
value: id # 值字段
|
||
association: 1 # 关联关系: 1=一对一, 2=一对多
|
||
hasDeletedAt: true # 关联表是否有软删除
|
||
|
||
# --- 时间字段示例 ---
|
||
- fieldName: PublishTime
|
||
fieldDesc: 发布时间
|
||
fieldType: time.Time
|
||
fieldJson: publishTime
|
||
columnName: publish_time
|
||
dataTypeLong: datetime
|
||
form: true
|
||
table: true
|
||
desc: true
|
||
require: false
|
||
clearable: true
|
||
sort: true
|
||
fieldSearchType: BETWEEN # 时间范围搜索
|
||
|
||
# ==================== 自定义查询方法（可选）====================
|
||
customMethods:
|
||
# --- 单条查询示例 ---
|
||
- name: FindByTitle # 方法名称
|
||
description: 根据标题查询 # 方法描述
|
||
returnType: single # 返回类型: single(单个), list(列表), count(计数), exists(存在检查)
|
||
params: # 方法参数
|
||
- name: title # 参数名
|
||
type: string # 参数类型
|
||
fieldName: Title # 对应字段名
|
||
conditions: # 查询条件
|
||
- fieldName: Title # 字段名
|
||
operator: eq # 操作符
|
||
paramName: title # 参数名
|
||
|
||
# --- 列表查询示例 ---
|
||
- name: GetPublishedArticles
|
||
description: 获取已发布的文章列表
|
||
returnType: list
|
||
params:
|
||
- name: status
|
||
type: int
|
||
fieldName: Status
|
||
conditions:
|
||
- fieldName: Status
|
||
operator: eq
|
||
paramName: status
|
||
orderBy: created_at DESC # 排序
|
||
limit: 100 # 限制数量
|
||
```
|
||
|
||
### JSON 格式完整示例
|
||
|
||
```json
|
||
{
|
||
"package": "example",
|
||
"structName": "Article",
|
||
"tableName": "articles",
|
||
"description": "文章管理",
|
||
"businessDB": "",
|
||
"abbreviation": "article",
|
||
"options": {
|
||
"gvaModel": true,
|
||
"autoMigrate": true,
|
||
"generateWeb": true,
|
||
"generateServer": true,
|
||
"onlyTemplate": false,
|
||
"isAdd": false,
|
||
"autoCreateApiToSql": true,
|
||
"autoCreateMenuToSql": true,
|
||
"autoCreateBtnAuth": true,
|
||
"autoCreateResource": false,
|
||
"isTree": false,
|
||
"treeJson": ""
|
||
},
|
||
"fields": [
|
||
{
|
||
"fieldName": "Title",
|
||
"fieldDesc": "标题",
|
||
"fieldType": "string",
|
||
"fieldJson": "title",
|
||
"columnName": "title",
|
||
"dataTypeLong": "varchar(255)",
|
||
"form": true,
|
||
"table": true,
|
||
"desc": true,
|
||
"excel": true,
|
||
"require": true,
|
||
"errorText": "请输入标题",
|
||
"clearable": true,
|
||
"sort": false,
|
||
"fieldSearchType": "LIKE",
|
||
"fieldSearchHide": false,
|
||
"fieldIndexType": ""
|
||
},
|
||
{
|
||
"fieldName": "Status",
|
||
"fieldDesc": "状态",
|
||
"fieldType": "int",
|
||
"fieldJson": "status",
|
||
"columnName": "status",
|
||
"dataTypeLong": "tinyint(1)",
|
||
"form": true,
|
||
"table": true,
|
||
"desc": true,
|
||
"require": false,
|
||
"defaultValue": "1",
|
||
"fieldSearchType": "EQ",
|
||
"dictType": "article_status"
|
||
},
|
||
{
|
||
"fieldName": "AuthorID",
|
||
"fieldDesc": "作者ID",
|
||
"fieldType": "uint",
|
||
"fieldJson": "authorId",
|
||
"columnName": "author_id",
|
||
"dataTypeLong": "bigint(20)",
|
||
"form": true,
|
||
"table": true,
|
||
"require": true,
|
||
"fieldSearchType": "EQ",
|
||
"fieldIndexType": "index",
|
||
"dataSource": {
|
||
"dbName": "",
|
||
"table": "sys_users",
|
||
"label": "nick_name",
|
||
"value": "id",
|
||
"association": 1,
|
||
"hasDeletedAt": true
|
||
}
|
||
}
|
||
],
|
||
"customMethods": [
|
||
{
|
||
"name": "FindByTitle",
|
||
"description": "根据标题查询",
|
||
"returnType": "single",
|
||
"params": [
|
||
{
|
||
"name": "title",
|
||
"type": "string",
|
||
"fieldName": "Title"
|
||
}
|
||
],
|
||
"conditions": [
|
||
{
|
||
"fieldName": "Title",
|
||
"operator": "eq",
|
||
"paramName": "title"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 配置项详细说明
|
||
|
||
#### 基础信息
|
||
|
||
| 属性 | 类型 | 必填 | 说明 | 示例 |
|
||
|------|------|------|------|------|
|
||
| `package` | string | 是 | 包名（小写） | `example` |
|
||
| `structName` | string | 是 | 结构体名称（大驼峰） | `Article` |
|
||
| `tableName` | string | 是 | 数据库表名 | `articles` |
|
||
| `description` | string | 是 | 功能描述 | `文章管理` |
|
||
| `businessDB` | string | 否 | 业务数据库名（空=默认） | `""` |
|
||
| `abbreviation` | string | 是 | 缩写（用于路由） | `article` |
|
||
|
||
#### 生成选项 (options)
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `gvaModel` | bool | `true` | 使用 KRA_MODEL（包含 ID, CreatedAt, UpdatedAt, DeletedAt） |
|
||
| `autoMigrate` | bool | `true` | 自动迁移数据库表结构 |
|
||
| `generateWeb` | bool | `true` | 生成前端代码 |
|
||
| `generateServer` | bool | `true` | 生成后端代码 |
|
||
| `onlyTemplate` | bool | `false` | 仅生成模板（不注入代码到现有文件） |
|
||
| `isAdd` | bool | `false` | 追加模式（不覆盖已有文件） |
|
||
| `autoCreateApiToSql` | bool | `true` | 自动创建 API 记录到 sys_apis 表 |
|
||
| `autoCreateMenuToSql` | bool | `true` | 自动创建菜单记录到 sys_base_menus 表 |
|
||
| `autoCreateBtnAuth` | bool | `true` | 自动创建按钮权限 |
|
||
| `autoCreateResource` | bool | `false` | 自动创建资源标识 |
|
||
| `isTree` | bool | `false` | 是否为树形结构数据 |
|
||
| `treeJson` | string | `""` | 树形结构展示字段（如: name, title） |
|
||
|
||
### 字段配置说明
|
||
|
||
#### 基础属性
|
||
|
||
| 属性 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `fieldName` | string | 是 | Go 结构体字段名（大驼峰） |
|
||
| `fieldDesc` | string | 是 | 字段描述/注释 |
|
||
| `fieldType` | string | 是 | Go 类型（string, int, uint, float64, bool, time.Time 等） |
|
||
| `fieldJson` | string | 是 | JSON 序列化字段名（小驼峰） |
|
||
| `columnName` | string | 是 | 数据库列名（下划线） |
|
||
| `dataTypeLong` | string | 是 | 数据库类型（如 varchar(255), bigint(20)） |
|
||
|
||
#### 显示属性
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `form` | bool | `false` | 是否显示在表单中 |
|
||
| `table` | bool | `false` | 是否显示在表格中 |
|
||
| `desc` | bool | `false` | 是否显示在详情页 |
|
||
| `excel` | bool | `false` | 是否支持导入/导出 |
|
||
|
||
#### 验证属性
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `require` | bool | `false` | 是否必填 |
|
||
| `defaultValue` | string | `""` | 默认值 |
|
||
| `errorText` | string | `""` | 校验失败提示文字 |
|
||
| `clearable` | bool | `true` | 是否可清空 |
|
||
|
||
#### 搜索属性
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `fieldSearchType` | string | `""` | 搜索类型（见下表） |
|
||
| `fieldSearchHide` | bool | `false` | 是否隐藏搜索条件（高级搜索） |
|
||
| `sort` | bool | `false` | 是否支持排序 |
|
||
|
||
**搜索类型说明：**
|
||
|
||
| 类型 | 说明 | 生成的 SQL 条件 |
|
||
|------|------|----------------|
|
||
| `LIKE` | 模糊匹配 | `WHERE title LIKE '%keyword%'` |
|
||
| `EQ` | 精确匹配 | `WHERE status = 1` |
|
||
| `BETWEEN` | 范围查询 | `WHERE created_at BETWEEN ? AND ?` |
|
||
| `GT` | 大于 | `WHERE price > 100` |
|
||
| `GTE` | 大于等于 | `WHERE price >= 100` |
|
||
| `LT` | 小于 | `WHERE price < 100` |
|
||
| `LTE` | 小于等于 | `WHERE price <= 100` |
|
||
| `NEQ` | 不等于 | `WHERE status != 0` |
|
||
|
||
#### 关联属性
|
||
|
||
| 属性 | 类型 | 默认值 | 说明 |
|
||
|------|------|--------|------|
|
||
| `dictType` | string | `""` | 字典类型（用于下拉选择） |
|
||
| `dataSource` | object | `null` | 数据源配置（关联其他表） |
|
||
| `fieldIndexType` | string | `""` | 索引类型（`index`, `unique`） |
|
||
| `primaryKey` | bool | `false` | 是否为主键 |
|
||
|
||
### 数据源配置 (dataSource)
|
||
|
||
用于配置字段与其他表的关联关系，生成下拉选择组件。
|
||
|
||
| 属性 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `dbName` | string | 否 | 数据库名（空表示当前数据库） |
|
||
| `table` | string | 是 | 关联表名 |
|
||
| `label` | string | 是 | 显示字段（用于下拉选项文本） |
|
||
| `value` | string | 是 | 值字段（用于下拉选项值） |
|
||
| `association` | int | 是 | 关联关系：`1`=一对一, `2`=一对多 |
|
||
| `hasDeletedAt` | bool | 否 | 关联表是否有软删除字段 |
|
||
|
||
**示例：**
|
||
|
||
```yaml
|
||
dataSource:
|
||
dbName: "" # 当前数据库
|
||
table: sys_users # 关联 sys_users 表
|
||
label: nick_name # 显示用户昵称
|
||
value: id # 值为用户 ID
|
||
association: 1 # 一对一关系
|
||
hasDeletedAt: true # sys_users 表有软删除
|
||
```
|
||
|
||
### 自定义查询方法 (customMethods)
|
||
|
||
用于生成 GORM Gen 自定义查询方法，适用于复杂查询场景。
|
||
|
||
#### 方法配置
|
||
|
||
| 属性 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `name` | string | 是 | 方法名称（如: FindByTitle, GetActiveUsers） |
|
||
| `description` | string | 否 | 方法描述 |
|
||
| `returnType` | string | 是 | 返回类型（见下表） |
|
||
| `params` | array | 是 | 方法参数列表 |
|
||
| `conditions` | array | 是 | 查询条件列表 |
|
||
| `orderBy` | string | 否 | 排序字段（如: `created_at DESC`） |
|
||
| `limit` | int | 否 | 限制数量（0 表示不限制） |
|
||
|
||
**返回类型说明：**
|
||
|
||
| 类型 | 说明 | 生成的方法签名 |
|
||
|------|------|---------------|
|
||
| `single` | 返回单条记录 | `func (r *repo) FindByTitle(ctx, title) (*Entity, error)` |
|
||
| `list` | 返回记录列表 | `func (r *repo) GetActiveUsers(ctx, status) ([]*Entity, error)` |
|
||
| `count` | 返回记录数量 | `func (r *repo) CountByStatus(ctx, status) (int64, error)` |
|
||
| `exists` | 返回是否存在 | `func (r *repo) ExistsByTitle(ctx, title) (bool, error)` |
|
||
|
||
#### 参数配置 (params)
|
||
|
||
| 属性 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `name` | string | 是 | 参数名称 |
|
||
| `type` | string | 是 | 参数类型（string, int, uint, bool, time.Time 等） |
|
||
| `fieldName` | string | 是 | 对应的字段名（用于生成查询条件） |
|
||
|
||
#### 条件配置 (conditions)
|
||
|
||
| 属性 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `fieldName` | string | 是 | 字段名 |
|
||
| `operator` | string | 是 | 操作符（见下表） |
|
||
| `paramName` | string | 是 | 参数名（对应 params 中的 name） |
|
||
|
||
**操作符说明：**
|
||
|
||
| 操作符 | 说明 | 生成的条件 |
|
||
|--------|------|-----------|
|
||
| `eq` | 等于 | `field.Eq(param)` |
|
||
| `neq` | 不等于 | `field.Neq(param)` |
|
||
| `gt` | 大于 | `field.Gt(param)` |
|
||
| `gte` | 大于等于 | `field.Gte(param)` |
|
||
| `lt` | 小于 | `field.Lt(param)` |
|
||
| `lte` | 小于等于 | `field.Lte(param)` |
|
||
| `like` | 模糊匹配 | `field.Like("%" + param + "%")` |
|
||
| `in` | 包含 | `field.In(params...)` |
|
||
| `between` | 范围 | `field.Between(start, end)` |
|
||
| `isNull` | 为空 | `field.IsNull()` |
|
||
| `isNotNull` | 不为空 | `field.IsNotNull()` |
|
||
|
||
#### 自定义方法示例
|
||
|
||
```yaml
|
||
customMethods:
|
||
# 根据标题精确查询单条记录
|
||
- name: FindByTitle
|
||
description: 根据标题查询文章
|
||
returnType: single
|
||
params:
|
||
- name: title
|
||
type: string
|
||
fieldName: Title
|
||
conditions:
|
||
- fieldName: Title
|
||
operator: eq
|
||
paramName: title
|
||
|
||
# 根据状态查询列表，带排序和限制
|
||
- name: GetPublishedArticles
|
||
description: 获取已发布的文章列表
|
||
returnType: list
|
||
params:
|
||
- name: status
|
||
type: int
|
||
fieldName: Status
|
||
conditions:
|
||
- fieldName: Status
|
||
operator: eq
|
||
paramName: status
|
||
orderBy: created_at DESC
|
||
limit: 100
|
||
|
||
# 统计指定作者的文章数量
|
||
- name: CountByAuthor
|
||
description: 统计作者的文章数量
|
||
returnType: count
|
||
params:
|
||
- name: authorId
|
||
type: uint
|
||
fieldName: AuthorID
|
||
conditions:
|
||
- fieldName: AuthorID
|
||
operator: eq
|
||
paramName: authorId
|
||
|
||
# 检查标题是否已存在
|
||
- name: ExistsByTitle
|
||
description: 检查标题是否已存在
|
||
returnType: exists
|
||
params:
|
||
- name: title
|
||
type: string
|
||
fieldName: Title
|
||
conditions:
|
||
- fieldName: Title
|
||
operator: eq
|
||
paramName: title
|
||
|
||
# 模糊搜索文章
|
||
- name: SearchByKeyword
|
||
description: 根据关键词搜索文章
|
||
returnType: list
|
||
params:
|
||
- name: keyword
|
||
type: string
|
||
fieldName: Title
|
||
conditions:
|
||
- fieldName: Title
|
||
operator: like
|
||
paramName: keyword
|
||
orderBy: created_at DESC
|
||
|
||
# 多条件查询
|
||
- name: FindByStatusAndAuthor
|
||
description: 根据状态和作者查询
|
||
returnType: list
|
||
params:
|
||
- name: status
|
||
type: int
|
||
fieldName: Status
|
||
- name: authorId
|
||
type: uint
|
||
fieldName: AuthorID
|
||
conditions:
|
||
- fieldName: Status
|
||
operator: eq
|
||
paramName: status
|
||
- fieldName: AuthorID
|
||
operator: eq
|
||
paramName: authorId
|
||
```
|
||
|
||
### Go 类型与数据库类型映射
|
||
|
||
| Go 类型 | 数据库类型 | TypeScript 类型 | 说明 |
|
||
|---------|-----------|-----------------|------|
|
||
| `string` | `varchar(n)`, `text`, `longtext` | `string` | 字符串 |
|
||
| `int` | `int`, `tinyint`, `smallint` | `number` | 整数 |
|
||
| `int64` | `bigint` | `number` | 长整数 |
|
||
| `uint` | `int unsigned`, `bigint unsigned` | `number` | 无符号整数 |
|
||
| `float64` | `float`, `double`, `decimal` | `number` | 浮点数 |
|
||
| `bool` | `tinyint(1)`, `boolean` | `boolean` | 布尔值 |
|
||
| `time.Time` | `datetime`, `timestamp`, `date` | `string` | 时间 |
|
||
| `datatypes.JSON` | `json`, `jsonb` | `object` | JSON 对象 |
|
||
| `[]byte` | `blob`, `binary` | `string` | 二进制数据 |
|
||
|
||
|
||
## Web 界面使用
|
||
|
||
### 访问代码生成器
|
||
|
||
1. 登录 KRA 管理后台
|
||
2. 导航到 `系统工具 > 代码生成器`
|
||
|
||
### 使用步骤
|
||
|
||
#### 1. 选择数据库和表
|
||
|
||
- 在左侧选择数据库连接
|
||
- 选择要生成代码的数据表
|
||
- 系统会自动读取表结构信息
|
||
|
||
#### 2. 配置基本信息
|
||
|
||
- **结构体名称**: Go 结构体名（大驼峰命名）
|
||
- **包名**: 代码包名（小写）
|
||
- **表名**: 数据库表名
|
||
- **描述**: 功能描述
|
||
- **缩写**: 用于路由和变量名
|
||
|
||
#### 3. 配置字段
|
||
|
||
对每个字段进行配置：
|
||
|
||
- **显示配置**: 表单、表格、详情页、导出
|
||
- **验证配置**: 必填、默认值、校验提示
|
||
- **搜索配置**: 搜索类型、是否隐藏
|
||
- **关联配置**: 字典类型、数据源
|
||
|
||
#### 4. 配置生成选项
|
||
|
||
- **基础配置**: KRA_MODEL、自动迁移
|
||
- **生成范围**: 后端代码、前端代码
|
||
- **自动注册**: API 记录、菜单记录、按钮权限
|
||
|
||
#### 5. 预览和生成
|
||
|
||
- 点击「预览」查看将要生成的代码
|
||
- 确认无误后点击「生成」
|
||
- 生成完成后可在历史记录中查看
|
||
|
||
### 历史记录管理
|
||
|
||
- 查看所有代码生成历史
|
||
- 支持代码回滚（删除生成的文件，移除注入的代码）
|
||
- 支持重新生成
|
||
|
||
## 模板自定义
|
||
|
||
KRA AutoCode 提供了灵活的模板自定义能力，允许开发者根据项目需求定制代码生成风格。本节详细介绍如何创建和使用自定义模板。
|
||
|
||
### 模板目录结构
|
||
|
||
默认模板位于 `resource/package/` 目录下：
|
||
|
||
```
|
||
resource/package/
|
||
├── server/ # 后端模板
|
||
│ ├── biz/ # Biz 层模板
|
||
│ │ ├── biz.go.tpl # Usecase + Repository 接口
|
||
│ │ └── enter.go.tpl # 包入口
|
||
│ ├── data/ # Data 层模板
|
||
│ │ ├── data.go.tpl # Repository 实现
|
||
│ │ ├── enter.go.tpl # 包入口
|
||
│ │ └── model.go.tpl # GORM Gen 模型
|
||
│ ├── handler/ # Handler 层模板
|
||
│ │ ├── handler.go.tpl # HTTP Handler
|
||
│ │ └── enter.go.tpl # 包入口
|
||
│ ├── service/ # Service 层模板
|
||
│ │ ├── service.go.tpl # Service 实现
|
||
│ │ └── enter.go.tpl # 包入口
|
||
│ ├── router/ # Router 层模板
|
||
│ │ ├── router.go.tpl # 路由配置
|
||
│ │ └── enter.go.tpl # 包入口
|
||
│ └── types/ # 类型定义模板
|
||
│ └── request.go.tpl # 请求/响应类型
|
||
├── web/ # 前端模板
|
||
│ ├── pages/ # React 页面模板
|
||
│ │ ├── index.tsx.tpl # 列表页面
|
||
│ │ ├── form.tsx.tpl # 表单组件
|
||
│ │ └── detail.tsx.tpl # 详情组件
|
||
│ ├── services/ # API 服务模板
|
||
│ │ └── api.ts.tpl # TypeScript API
|
||
│ └── types/ # 类型定义模板
|
||
│ └── types.d.ts.tpl # TypeScript 类型
|
||
└── readme.txt.tpl # 说明文件
|
||
```
|
||
|
||
### 模板语法基础
|
||
|
||
模板使用 Go 的 `text/template` 语法。以下是常用语法：
|
||
|
||
#### 变量输出
|
||
|
||
```go
|
||
// 输出变量
|
||
{{.StructName}}
|
||
|
||
// 输出嵌套变量
|
||
{{.PrimaryField.FieldName}}
|
||
```
|
||
|
||
#### 条件判断
|
||
|
||
```go
|
||
{{- if .GvaModel }}
|
||
// 使用 KRA_MODEL 时的代码
|
||
{{- else }}
|
||
// 不使用 KRA_MODEL 时的代码
|
||
{{- end }}
|
||
|
||
// 多条件判断
|
||
{{- if and .HasDataSource .Form }}
|
||
// 同时满足两个条件
|
||
{{- end }}
|
||
|
||
{{- if or .IsTree .HasDataSource }}
|
||
// 满足任一条件
|
||
{{- end }}
|
||
|
||
// 非判断
|
||
{{- if not .OnlyTemplate }}
|
||
// 不是仅模板模式
|
||
{{- end }}
|
||
```
|
||
|
||
#### 循环遍历
|
||
|
||
```go
|
||
// 遍历字段列表
|
||
{{- range .Fields }}
|
||
{{.FieldName}}: {{.FieldType}}
|
||
{{- end }}
|
||
|
||
// 带索引的遍历
|
||
{{- range $index, $field := .Fields }}
|
||
// $index 是索引，$field 是字段
|
||
{{- end }}
|
||
|
||
// 遍历 Map
|
||
{{- range $key, $value := .DataSourceMap }}
|
||
{{$key}}: {{$value.Table}}
|
||
{{- end }}
|
||
```
|
||
|
||
#### 空白控制
|
||
|
||
```go
|
||
// {{- 去除左侧空白
|
||
// -}} 去除右侧空白
|
||
{{- if .Condition -}}
|
||
内容
|
||
{{- end -}}
|
||
```
|
||
|
||
### 模板变量详解
|
||
|
||
#### 基础信息变量
|
||
|
||
| 变量 | 类型 | 说明 | 示例值 |
|
||
|------|------|------|--------|
|
||
| `{{.Package}}` | string | 包名（小写） | `example` |
|
||
| `{{.PackageName}}` | string | 包名（小写） | `example` |
|
||
| `{{.PackageT}}` | string | 包名（首字母大写） | `Example` |
|
||
| `{{.StructName}}` | string | 结构体名（大驼峰） | `Article` |
|
||
| `{{.TableName}}` | string | 数据库表名 | `articles` |
|
||
| `{{.Description}}` | string | 功能描述 | `文章管理` |
|
||
| `{{.Abbreviation}}` | string | 缩写（用于路由） | `article` |
|
||
| `{{.Module}}` | string | Go 模块名 | `github.com/xxx/kra` |
|
||
| `{{.HumpPackageName}}` | string | 驼峰包名 | `example` |
|
||
| `{{.BusinessDB}}` | string | 业务数据库名 | `""` |
|
||
|
||
#### 字段相关变量
|
||
|
||
| 变量 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `{{.Fields}}` | []*AutoCodeField | 字段列表 |
|
||
| `{{.PrimaryField}}` | *AutoCodeField | 主键字段 |
|
||
| `{{.DictTypes}}` | []string | 字典类型列表 |
|
||
| `{{.DataSourceMap}}` | map[string]*DataSource | 数据源映射 |
|
||
|
||
#### 选项变量
|
||
|
||
| 变量 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `{{.GvaModel}}` | bool | 是否使用 KRA_MODEL |
|
||
| `{{.AutoMigrate}}` | bool | 是否自动迁移 |
|
||
| `{{.AutoCreateResource}}` | bool | 是否创建资源标识 |
|
||
| `{{.AutoCreateApiToSql}}` | bool | 是否自动创建 API 记录 |
|
||
| `{{.AutoCreateMenuToSql}}` | bool | 是否自动创建菜单 |
|
||
| `{{.AutoCreateBtnAuth}}` | bool | 是否自动创建按钮权限 |
|
||
| `{{.OnlyTemplate}}` | bool | 是否仅生成模板 |
|
||
| `{{.IsAdd}}` | bool | 是否追加模式 |
|
||
| `{{.IsTree}}` | bool | 是否树形结构 |
|
||
| `{{.TreeJson}}` | string | 树形展示字段 |
|
||
| `{{.GenerateWeb}}` | bool | 是否生成前端 |
|
||
| `{{.GenerateServer}}` | bool | 是否生成后端 |
|
||
|
||
#### 特性标记变量
|
||
|
||
| 变量 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `{{.HasPic}}` | bool | 是否有图片字段 |
|
||
| `{{.HasFile}}` | bool | 是否有文件字段 |
|
||
| `{{.HasTimer}}` | bool | 是否有时间字段 |
|
||
| `{{.HasRichText}}` | bool | 是否有富文本字段 |
|
||
| `{{.HasDataSource}}` | bool | 是否有数据源字段 |
|
||
| `{{.HasSearchTimer}}` | bool | 是否有时间搜索字段 |
|
||
| `{{.HasArray}}` | bool | 是否有数组字段 |
|
||
| `{{.HasExcel}}` | bool | 是否有导出字段 |
|
||
| `{{.NeedSort}}` | bool | 是否需要排序 |
|
||
| `{{.NeedJSON}}` | bool | 是否需要 JSON 类型 |
|
||
| `{{.HasCustomMethods}}` | bool | 是否有自定义方法 |
|
||
|
||
#### 字段对象属性
|
||
|
||
每个字段对象 (`AutoCodeField`) 包含以下属性：
|
||
|
||
| 属性 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `.FieldName` | string | Go 字段名（大驼峰） |
|
||
| `.FieldDesc` | string | 字段描述 |
|
||
| `.FieldType` | string | Go 类型 |
|
||
| `.FieldJson` | string | JSON 字段名（小驼峰） |
|
||
| `.ColumnName` | string | 数据库列名 |
|
||
| `.DataTypeLong` | string | 数据库类型 |
|
||
| `.Comment` | string | 字段注释 |
|
||
| `.FieldSearchType` | string | 搜索类型 |
|
||
| `.FieldSearchHide` | bool | 是否隐藏搜索 |
|
||
| `.DictType` | string | 字典类型 |
|
||
| `.Form` | bool | 是否显示在表单 |
|
||
| `.Table` | bool | 是否显示在表格 |
|
||
| `.Desc` | bool | 是否显示在详情 |
|
||
| `.Excel` | bool | 是否支持导出 |
|
||
| `.Require` | bool | 是否必填 |
|
||
| `.DefaultValue` | string | 默认值 |
|
||
| `.ErrorText` | string | 校验失败提示 |
|
||
| `.Clearable` | bool | 是否可清空 |
|
||
| `.Sort` | bool | 是否支持排序 |
|
||
| `.PrimaryKey` | bool | 是否主键 |
|
||
| `.DataSource` | *DataSource | 数据源配置 |
|
||
| `.CheckDataSource` | bool | 是否有数据源 |
|
||
| `.FieldIndexType` | string | 索引类型 |
|
||
|
||
### 模板函数详解
|
||
|
||
#### 类型转换函数
|
||
|
||
**GenerateTSType** - Go 类型转 TypeScript 类型
|
||
|
||
```go
|
||
// 用法
|
||
{{ GenerateTSType .FieldType }}
|
||
|
||
// 类型映射
|
||
// string -> string
|
||
// int, int64, uint, float64 -> number
|
||
// bool -> boolean
|
||
// time.Time -> string
|
||
// json, array -> object
|
||
```
|
||
|
||
**GenerateModelField** - 生成 GORM Gen 模型字段
|
||
|
||
```go
|
||
// 用法
|
||
{{ GenerateModelField . }}
|
||
|
||
// 输出示例
|
||
Title string `gorm:"column:title;type:varchar(255);comment:标题" json:"title"` // 标题
|
||
```
|
||
|
||
#### 代码生成函数
|
||
|
||
**GenerateGormGenSearchConditions** - 生成 GORM Gen 搜索条件
|
||
|
||
```go
|
||
// 用法
|
||
{{ GenerateGormGenSearchConditions .Fields .StructName }}
|
||
|
||
// 输出示例
|
||
if req.Title != nil && *req.Title != "" {
|
||
q = q.Where(t.Title.Like("%" + *req.Title + "%"))
|
||
}
|
||
if req.Status != nil {
|
||
q = q.Where(t.Status.Eq(*req.Status))
|
||
}
|
||
```
|
||
|
||
**GenerateReactFormItem** - 生成 React 表单项
|
||
|
||
```go
|
||
// 用法
|
||
{{ GenerateReactFormItem . }}
|
||
|
||
// 输出示例（根据字段类型自动生成）
|
||
<Form.Item name="title" label="标题" rules={[{ required: true, message: '请输入标题' }]}>
|
||
<Input placeholder="请输入标题" allowClear />
|
||
</Form.Item>
|
||
```
|
||
|
||
**GenerateReactProTableColumn** - 生成 ProTable 列配置
|
||
|
||
```go
|
||
// 用法
|
||
{{ GenerateReactProTableColumn . }}
|
||
|
||
// 输出示例
|
||
{
|
||
title: '标题',
|
||
dataIndex: 'title',
|
||
valueType: 'text',
|
||
sorter: true,
|
||
},
|
||
```
|
||
|
||
**GenerateReactSearchFormItem** - 生成搜索表单项
|
||
|
||
```go
|
||
// 用法
|
||
{{ GenerateReactSearchFormItem . }}
|
||
|
||
// 根据 FieldSearchType 生成不同的搜索组件
|
||
// LIKE -> Input
|
||
// EQ -> Select/Input
|
||
// BETWEEN -> DatePicker.RangePicker
|
||
```
|
||
|
||
**GenerateReactDescriptionItem** - 生成详情描述项
|
||
|
||
```go
|
||
// 用法
|
||
{{ GenerateReactDescriptionItem . }}
|
||
|
||
// 输出示例
|
||
<Descriptions.Item label="标题">{currentRecord?.title}</Descriptions.Item>
|
||
```
|
||
|
||
**GenerateReactDefaultValue** - 生成默认值
|
||
|
||
```go
|
||
// 用法
|
||
{{ GenerateReactDefaultValue . }}
|
||
|
||
// 根据字段类型生成默认值
|
||
// string -> ''
|
||
// int -> 0
|
||
// bool -> false
|
||
// time.Time -> undefined
|
||
```
|
||
|
||
#### 自定义方法函数
|
||
|
||
**GenerateCustomMethodInterface** - 生成自定义方法接口
|
||
|
||
```go
|
||
// 用法
|
||
{{ GenerateCustomMethodInterface .CustomMethods .StructName .Package }}
|
||
|
||
// 输出示例
|
||
FindByTitle(ctx context.Context, title string) (*example.Article, error)
|
||
GetPublishedArticles(ctx context.Context, status int) ([]*example.Article, error)
|
||
```
|
||
|
||
**GenerateCustomMethodImpl** - 生成自定义方法实现
|
||
|
||
```go
|
||
// 用法
|
||
{{ GenerateCustomMethodImpl .CustomMethods .StructName .Package .Abbreviation }}
|
||
|
||
// 输出示例
|
||
func (r *articleRepo) FindByTitle(ctx context.Context, title string) (*example.Article, error) {
|
||
t := query.Article
|
||
m, err := t.WithContext(ctx).Where(t.Title.Eq(title)).First()
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
return toBizArticle(m), nil
|
||
}
|
||
```
|
||
|
||
#### 字符串处理函数
|
||
|
||
| 函数 | 说明 | 输入 | 输出 |
|
||
|------|------|------|------|
|
||
| `title` | 首字母大写 | `hello` | `Hello` |
|
||
| `toPascalCase` | 转大驼峰 | `user_name` | `UserName` |
|
||
| `ToCamelCase` | 转大驼峰 | `user_name` | `UserName` |
|
||
| `ToLowerCamelCase` | 转小驼峰 | `user_name` | `userName` |
|
||
| `ToSnakeCase` | 转下划线 | `UserName` | `user_name` |
|
||
| `FirstLower` | 首字母小写 | `UserName` | `userName` |
|
||
| `FirstUpper` | 首字母大写 | `userName` | `UserName` |
|
||
|
||
### 创建自定义模板
|
||
|
||
#### 步骤 1：复制默认模板
|
||
|
||
```bash
|
||
# 复制默认模板到自定义目录
|
||
cp -r resource/package my-templates
|
||
```
|
||
|
||
#### 步骤 2：修改模板文件
|
||
|
||
根据项目需求修改模板文件。以下是一些常见的自定义场景：
|
||
|
||
**场景 1：修改 Handler 响应格式**
|
||
|
||
编辑 `my-templates/server/handler/handler.go.tpl`：
|
||
|
||
```go
|
||
// 修改响应格式
|
||
func (h *{{.StructName}}Handler) Create{{.StructName}}(c *gin.Context) {
|
||
var req request.{{.StructName}}Request
|
||
if err := c.ShouldBindJSON(&req); err != nil {
|
||
// 自定义错误响应
|
||
c.JSON(400, gin.H{
|
||
"code": 400,
|
||
"message": err.Error(),
|
||
"data": nil,
|
||
})
|
||
return
|
||
}
|
||
// ... 其他代码
|
||
}
|
||
```
|
||
|
||
**场景 2：添加自定义日志**
|
||
|
||
编辑 `my-templates/server/biz/biz.go.tpl`：
|
||
|
||
```go
|
||
// Create 创建{{.Description}}
|
||
func (uc *{{.StructName}}Usecase) Create(ctx context.Context, {{.Abbreviation}} *{{.Package}}.{{.StructName}}) error {
|
||
// 添加自定义日志
|
||
uc.log.WithContext(ctx).Infof("[自定义日志] 开始创建{{.Description}}, 数据: %+v", {{.Abbreviation}})
|
||
|
||
if err := uc.repo.Create(ctx, {{.Abbreviation}}); err != nil {
|
||
uc.log.WithContext(ctx).Errorf("[自定义日志] 创建{{.Description}}失败: %v", err)
|
||
return err
|
||
}
|
||
|
||
uc.log.WithContext(ctx).Infof("[自定义日志] 创建{{.Description}}成功, ID: %v", {{.Abbreviation}}.{{.PrimaryField.FieldName}})
|
||
return nil
|
||
}
|
||
```
|
||
|
||
**场景 3：自定义前端组件样式**
|
||
|
||
编辑 `my-templates/web/pages/index.tsx.tpl`：
|
||
|
||
```tsx
|
||
// 添加自定义样式
|
||
const {{.StructName}}Page: React.FC = () => {
|
||
return (
|
||
<PageContainer
|
||
header={{
|
||
title: '{{.Description}}管理',
|
||
// 自定义头部样式
|
||
style: { backgroundColor: '#f5f5f5' },
|
||
}}
|
||
>
|
||
{/* 自定义内容 */}
|
||
</PageContainer>
|
||
);
|
||
};
|
||
```
|
||
|
||
#### 步骤 3：使用自定义模板
|
||
|
||
```bash
|
||
# 使用自定义模板生成代码
|
||
kra-gen generate -c autocode.yaml -t my-templates
|
||
|
||
# 或者设置环境变量
|
||
export KRA_TEMPLATE_DIR=my-templates
|
||
kra-gen generate -c autocode.yaml
|
||
```
|
||
|
||
### 模板开发最佳实践
|
||
|
||
#### 1. 使用条件判断处理可选功能
|
||
|
||
```go
|
||
{{- if .GvaModel }}
|
||
// 使用 KRA_MODEL 时包含 ID, CreatedAt, UpdatedAt, DeletedAt
|
||
type {{.StructName}} struct {
|
||
global.KRA_MODEL
|
||
{{- range .Fields}}
|
||
{{- if not .PrimaryKey}}
|
||
{{.FieldName}} {{.FieldType}} `json:"{{.FieldJson}}"`
|
||
{{- end}}
|
||
{{- end}}
|
||
}
|
||
{{- else }}
|
||
// 不使用 KRA_MODEL 时手动定义所有字段
|
||
type {{.StructName}} struct {
|
||
{{- range .Fields}}
|
||
{{.FieldName}} {{.FieldType}} `json:"{{.FieldJson}}"`
|
||
{{- end}}
|
||
}
|
||
{{- end }}
|
||
```
|
||
|
||
#### 2. 使用追加模式支持增量生成
|
||
|
||
```go
|
||
{{- if .IsAdd}}
|
||
// 追加模式：只生成新增字段的代码片段
|
||
// 在 {{.StructName}}Repo 接口中新增如下方法
|
||
// 请根据实际需求添加
|
||
|
||
{{- else}}
|
||
// 完整模式：生成完整的代码文件
|
||
package {{.Package}}
|
||
|
||
// ... 完整代码
|
||
{{- end}}
|
||
```
|
||
|
||
#### 3. 处理特殊字段类型
|
||
|
||
```go
|
||
{{- range .Fields}}
|
||
{{- if eq .FieldType "time.Time" }}
|
||
// 时间类型字段特殊处理
|
||
{{.FieldName}} time.Time `json:"{{.FieldJson}}"`
|
||
{{- else if eq .FieldType "json" }}
|
||
// JSON 类型字段特殊处理
|
||
{{.FieldName}} datatypes.JSON `json:"{{.FieldJson}}"`
|
||
{{- else }}
|
||
// 普通字段
|
||
{{.FieldName}} {{.FieldType}} `json:"{{.FieldJson}}"`
|
||
{{- end }}
|
||
{{- end }}
|
||
```
|
||
|
||
#### 4. 使用模板函数简化代码
|
||
|
||
```go
|
||
// 不推荐：手动处理类型转换
|
||
{{- if eq .FieldType "int" }}
|
||
number
|
||
{{- else if eq .FieldType "string" }}
|
||
string
|
||
{{- else if eq .FieldType "bool" }}
|
||
boolean
|
||
{{- end }}
|
||
|
||
// 推荐：使用模板函数
|
||
{{ GenerateTSType .FieldType }}
|
||
```
|
||
|
||
#### 5. 保持模板可读性
|
||
|
||
```go
|
||
// 使用注释说明模板逻辑
|
||
{{/* 生成 CRUD 方法 */}}
|
||
{{- if not .OnlyTemplate }}
|
||
|
||
{{/* 创建方法 */}}
|
||
func (uc *{{.StructName}}Usecase) Create(ctx context.Context, {{.Abbreviation}} *{{.Package}}.{{.StructName}}) error {
|
||
// ...
|
||
}
|
||
|
||
{{/* 删除方法 */}}
|
||
func (uc *{{.StructName}}Usecase) Delete(ctx context.Context, {{.PrimaryField.FieldJson}} {{.PrimaryField.FieldType}}) error {
|
||
// ...
|
||
}
|
||
|
||
{{- end }}
|
||
```
|
||
|
||
### 模板调试技巧
|
||
|
||
#### 1. 使用预览模式测试模板
|
||
|
||
```bash
|
||
# 预览生成的代码，不写入文件
|
||
kra-gen preview -c autocode.yaml -t my-templates --full
|
||
```
|
||
|
||
#### 2. 检查模板语法错误
|
||
|
||
```bash
|
||
# 详细输出模式，显示模板解析过程
|
||
kra-gen generate -c autocode.yaml -t my-templates -v
|
||
```
|
||
|
||
#### 3. 逐步调试
|
||
|
||
```go
|
||
// 在模板中添加调试输出
|
||
{{/* DEBUG: 当前字段信息 */}}
|
||
// FieldName: {{.FieldName}}
|
||
// FieldType: {{.FieldType}}
|
||
// FieldSearchType: {{.FieldSearchType}}
|
||
```
|
||
|
||
### 模板版本管理
|
||
|
||
建议将自定义模板纳入版本控制：
|
||
|
||
```bash
|
||
# 项目结构
|
||
my-project/
|
||
├── resource/
|
||
│ └── package/ # 默认模板（不修改）
|
||
├── templates/
|
||
│ └── custom/ # 自定义模板（纳入版本控制）
|
||
│ ├── server/
|
||
│ └── web/
|
||
└── .gitignore
|
||
```
|
||
|
||
```gitignore
|
||
# .gitignore
|
||
# 忽略默认模板
|
||
resource/package/
|
||
|
||
# 保留自定义模板
|
||
!templates/custom/
|
||
```
|
||
|
||
|
||
## 生成的代码结构
|
||
|
||
### 后端代码结构
|
||
|
||
```
|
||
internal/
|
||
├── biz/ # 业务逻辑层
|
||
│ └── {package}/
|
||
│ ├── {entity}.go # Usecase + Repository 接口
|
||
│ └── enter.go # 包入口，Wire Provider
|
||
├── data/ # 数据访问层
|
||
│ ├── model/ # GORM Gen 模型
|
||
│ │ └── {package}/
|
||
│ │ └── {entity}.go # 模型定义
|
||
│ └── {package}/
|
||
│ ├── {entity}.go # Repository 实现
|
||
│ └── enter.go # 包入口
|
||
├── service/ # 服务层
|
||
│ ├── types/ # 请求/响应类型
|
||
│ │ └── {package}/
|
||
│ │ └── request/
|
||
│ │ └── {entity}.go # 请求结构体
|
||
│ └── {package}/
|
||
│ ├── {entity}.go # Service 实现
|
||
│ └── enter.go # 包入口
|
||
└── server/
|
||
├── handler/ # HTTP Handler
|
||
│ └── {package}/
|
||
│ ├── {entity}.go # Handler 实现
|
||
│ └── enter.go # 包入口
|
||
└── router/ # 路由配置
|
||
└── {package}/
|
||
├── {entity}.go # 路由注册
|
||
└── enter.go # 包入口
|
||
```
|
||
|
||
### 前端代码结构
|
||
|
||
```
|
||
web/src/
|
||
├── pages/ # 页面组件
|
||
│ └── {package}/
|
||
│ └── {entity}/
|
||
│ ├── index.tsx # 列表页面（ProTable）
|
||
│ ├── form.tsx # 表单组件（Modal Form）
|
||
│ └── detail.tsx # 详情组件（Descriptions）
|
||
├── services/kratos/ # API 服务
|
||
│ └── {package}.ts # TypeScript API 调用
|
||
└── types/ # 类型定义
|
||
└── {package}/
|
||
└── {entity}.d.ts # TypeScript 类型
|
||
```
|
||
|
||
### 生成的 API 接口
|
||
|
||
| 接口 | 方法 | 路径 | 说明 |
|
||
|------|------|------|------|
|
||
| 创建 | POST | `/{abbr}/create{Struct}` | 创建记录 |
|
||
| 删除 | DELETE | `/{abbr}/delete{Struct}` | 删除单条记录 |
|
||
| 批量删除 | DELETE | `/{abbr}/delete{Struct}ByIds` | 批量删除 |
|
||
| 更新 | PUT | `/{abbr}/update{Struct}` | 更新记录 |
|
||
| 查询 | GET | `/{abbr}/find{Struct}` | 根据 ID 查询 |
|
||
| 列表 | GET | `/{abbr}/get{Struct}List` | 分页列表查询 |
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何只生成后端代码？
|
||
|
||
使用 `--no-web` 参数：
|
||
|
||
```bash
|
||
kra-gen generate -c autocode.yaml --no-web
|
||
```
|
||
|
||
### Q: 如何只生成前端代码？
|
||
|
||
使用 `--no-server` 参数：
|
||
|
||
```bash
|
||
kra-gen generate -c autocode.yaml --no-server
|
||
```
|
||
|
||
### Q: 如何避免覆盖已有文件？
|
||
|
||
使用 `--add` 参数启用追加模式：
|
||
|
||
```bash
|
||
kra-gen generate -c autocode.yaml --add
|
||
```
|
||
|
||
### Q: 如何只生成模板文件，不注入代码？
|
||
|
||
使用 `--only-template` 参数：
|
||
|
||
```bash
|
||
kra-gen generate -c autocode.yaml --only-template
|
||
```
|
||
|
||
### Q: 如何回滚生成的代码？
|
||
|
||
1. 通过 Web 界面：`系统工具 > 代码生成器 > 历史记录 > 回滚`
|
||
2. 手动删除生成的文件和注入的代码
|
||
|
||
### Q: 如何处理树形结构数据？
|
||
|
||
使用 `--tree` 和 `--tree-json` 参数：
|
||
|
||
```bash
|
||
kra-gen generate -c autocode.yaml --tree --tree-json name
|
||
```
|
||
|
||
或在配置文件中设置：
|
||
|
||
```yaml
|
||
options:
|
||
isTree: true
|
||
treeJson: name
|
||
```
|
||
|
||
### Q: 如何配置字典类型？
|
||
|
||
在字段配置中设置 `dictType`：
|
||
|
||
```yaml
|
||
fields:
|
||
- fieldName: Status
|
||
dictType: article_status # 字典类型名称
|
||
```
|
||
|
||
确保在系统中已创建对应的字典数据。
|
||
|
||
### Q: 如何配置数据源（关联其他表）？
|
||
|
||
在字段配置中设置 `dataSource`：
|
||
|
||
```yaml
|
||
fields:
|
||
- fieldName: AuthorID
|
||
dataSource:
|
||
table: sys_users # 关联表名
|
||
label: nick_name # 显示字段
|
||
value: id # 值字段
|
||
association: 1 # 1=一对一, 2=一对多
|
||
hasDeletedAt: true # 是否有软删除
|
||
```
|
||
|
||
### Q: 生成的代码如何与 Wire 集成？
|
||
|
||
生成的代码会自动：
|
||
1. 在各层的 `enter.go` 中导出 Provider
|
||
2. 注入到 `wire.go` 的 ProviderSet 中
|
||
3. 运行 `wire` 命令重新生成依赖注入代码
|
||
|
||
```bash
|
||
cd cmd/kratos-admin
|
||
wire
|
||
```
|
||
|
||
### Q: 如何自定义生成的代码风格？
|
||
|
||
1. 复制模板目录
|
||
2. 修改模板文件
|
||
3. 使用 `--template` 参数指定自定义模板
|
||
|
||
```bash
|
||
kra-gen generate -c autocode.yaml -t /path/to/custom/templates
|
||
```
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.0
|
||
|
||
- 初始版本
|
||
- 支持 Kratos DDD 架构代码生成
|
||
- 支持 GORM Gen 数据层
|
||
- 支持 React TypeScript 前端
|
||
- 支持 CLI 和 Web 界面
|
||
- 支持多数据库（MySQL、PostgreSQL、SQLite）
|