GOAT 入门

开始使用 Goat

Goat 是一个现代化的代码生成器和自动化环境，可帮助你快速开发完整应用程序，同时不失去对代码的控制。

Goat 不会将生成视为一次性的项目模板创建，而是允许你安全且有选择地向现有应用程序引入后续更改。生成的代码仍然是普通源代码——你可以像处理项目其余部分一样，手动修改、扩展并提交它。

你可以通过以下方式创建新项目：

goat init ./my-project \
  --name my-project \
  --git-repo https://github.com/your-user/my-project.git

该命令会基于预先准备好的 Git 仓库初始化应用程序，并创建可供后续工作的现成起点。

默认的 Goat 起步模板提供基于 Go 和 Angular 的应用程序，但生成器机制本身具有灵活性，可适配特定项目的架构和约定。

为什么选择 Goat？

业务应用程序开发中的大量工作都具有重复性：数据模型、DTO、DAO、表单、端点、验证、迁移以及基本的 CRUD 操作。

Goat 会自动化这一层工作，让你能够专注于真正使应用程序与众不同的内容：

• 业务逻辑，
• 安全性，
• 界面质量，
• 集成，
• 性能，
• 为用户创造价值的功能。

同时，共享的应用程序模型有助于保持前端和后端之间的一致性。基于该模型，可以生成实体、DTO、DAO、API 端点及其对应的界面元素等内容。

生成器的目标是加快工作，而不是将用户限制在预设的生成模型中。

因此，你可以在 Goat 能够带来实际时间节省的地方使用它，然后自由地手动扩展生成的代码。

安全执行脚本

Goat 的主要设计原则之一是将自动化与主机系统隔离。

典型的开发工具通常会直接在开发者的计算机上执行安装脚本。例如，npm install 可能会运行来自已安装依赖项的代码。

Goat 限制了此类风险的暴露面。

由 Goat 运行的脚本在隔离环境中执行，并且只能操作明确向其提供的资源。在典型场景中，这主要是指当前项目目录。

因此，自动化：

• 不会获得对主机系统的任意访问权限，
• 不应修改当前项目之外的文件，
• 可以运行 Node.js、npm 或 PostgreSQL 等工具，而无需在本地安装它们，
• 可在不同操作系统上保持相似的运行环境。

Docker 在这里提供隔离和可移植性层，而 Goat 则提供了定义和运行完整开发流程的便捷方式。

能够适应项目的生成器

Goat 不假设生成的代码必须保持不变。

你可以自由地手动编辑代码。生成器则应尽可能以局部且有意识的方式引入更改，而不是每次都覆盖整个应用程序模块。

这样便可以结合两种工作方式：

生成重复性内容，以及手动开发项目特有内容。

这种方式在较大型项目中尤为重要：生成器必须与开发人员在数月甚至数年内持续演进的代码共存。

Goat 与 AI

受限的声明式项目模型同样非常适合与 AI 工具协作。

模型无需分析仓库中的大量内容，通常只需处理更精简的领域描述和生成器配置即可。

这可以：

• 减少传递给模型的代码量，
• 降低使用 AI 的成本，
• 缩短项目分析时间，
• 减少 AI 需要修改的位置数量，
• 提高生成变更的可预测性。

因此，AI 可以主要协助修改应用程序的模型和意图，而 Goat 则负责将这些变更一致地转换为代码。

但这并不意味着必须完全在模型层面工作。如果某项具体变更直接在代码中完成更简单，生成的文件仍然可以像普通文件一样编辑。

此项目适用于谁

当你构建基于结构化数据、表单、API 和管理面板的应用程序，并希望快速从领域模型推进到可运行系统时，请选择 Goat。

基本工作流很简单：

1. 使用 goat init 创建项目，
2. 在 herd/_model.goat 中描述实体和关系，
3. 运行生成器，
4. Goat 创建或更新应用程序中的相关组件，
5. 在需要自定义逻辑的地方继续开发生成的代码。

Goat 特别适合包含大量重复性基础设施、但同时需要自定义业务逻辑和后续手动开发的应用程序。

要求

• Docker，
• Go —— 如果你直接在主机上运行 go run ./scripts ... 命令，
• Git 以及标准 Shell 工具。

无需在计算机上直接安装 PostgreSQL 或 Node.js。herd/*.goat 脚本可以在容器内启动所需的工具和服务。

快速开始

1. 创建项目

在新目录中运行：

goat init ./my-project \
  --name my-project \
  --git-repo https://github.com/your-user/my-project.git

该命令会基于预先准备好的 Git 仓库创建一个新项目。

这样，你将立即获得完整的项目结构，其中包括：

• 示例应用程序模型，
• 生成器配置，
• .goat 脚本，
• 示例 fixture 数据，
• 与当前项目版本匹配的文档，
• 可供进一步开发的后端和前端。

因此，goat init 不仅用于创建空项目，还用于准备一个完整的初始环境，可立即运行、分析和修改。

2. 配置环境

填写本地文件：

.env

不要将真实的密钥提交到仓库中。

数据库密码或 GOAT_JWT_SECRET 等值应保留在本地，或由对应环境的密钥管理系统提供。

3. 启动开发环境

运行：

bash child/dev.sh

如果你直接使用项目的源工具，也可以使用：

go run ./scripts run:script --path=herd/dev.goat

该脚本会准备完整的本地开发环境。

首次运行时，Goat 将会执行以下操作：

• 启动所需服务，
• 生成应用程序，
• 准备数据库，
• 执行迁移，
• 构建所需的项目组件，
• 从 herd/fixture.goat 加载数据，
• 启动后端和前端。

4. 打开应用程序

初始化完成后，应用程序可通过以下地址访问：

http://localhost:8080

其他服务：

• pgAdmin：http://localhost:5050，
• PostgreSQL：localhost:5433。

借助项目提供的 fixture，从首次启动开始，你不仅可以看到正常运行的应用程序，还能看到示例数据以及与当前使用的 Goat 版本相对应的文档。

接下来做什么？

启动项目后，你通常会按照以下循环进行工作：

修改模型或代码
        ↓
goat re
        ↓
检查变更
        ↓
手动完善
        ↓
测试

应用程序模型位于：

herd/_model.goat

修改后，你可以重新生成代码：

goat re

然后检查结果：

git diff

并运行测试：

goat run:script --path=herd/test.goat

后续步骤

• 按步骤学习[从 goat init 到第一个模型](/doc/zh/new-project)。
• 了解[项目架构](/doc/zh/project-architecture)。
• 配置[本地环境](/doc/zh/environment-configuration)。
• 查看如何修改[数据模型并生成代码](/doc/zh/data-model-and-code-generation)。
• 了解如何通过 harness 模块向[AI 助手提供数据](/doc/zh/harness-module)。
• 了解[本地开发工作流](/doc/zh/local-development)。
• 查看[测试与可用命令](/doc/zh/testing-and-commands)。