企业官网建设流程全解析

• 后端
• Web框架

Gii 是 Yii 2 内置的代码生成工具，它以 Web 模块的形式提供，允许开发者通过表单交互自动生成实现常见网站功能的代码，例如 Active Record 模型类、查询（Search）模型以及完整的 CRUD（增删改查）操作。本指南基于 docs/guide-fr/start-gii.md（与英文原版 docs/guide/start-gii.md 对应）展开，带领你完成在应用内启用 Gii、生成country数据表的模型与 CRUD 代码、并在浏览器中验证功能的完整流程，同时结合仓库源码揭示 Gii 作为模块被加载与执行的底层机制。读完本文，你将掌握用 Gii 快速搭建数据驱动页面的标准工作流，并了解如何基于生成代码进行二次定制。

Gii 是什么：一个以"模块"形态存在的代码生成器

Gii 在 Yii 2 中不是一个独立的命令行程序，而是作为框架的**模块（Module）**提供。在 Yii 中，模块是自包含的"子应用"，拥有自己的 MVC 元素（模型、视图、控制器），并且可以继续包含子模块。这一机制在框架源码中有明确对应：模块的基类yii\base\Module继承自ServiceLocator，维护$id、$module（父模块）、$modules（子模块映射）等核心属性，并定义了EVENT_BEFORE_ACTION与EVENT_AFTER_ACTION两个生命周期事件（framework/base/Module.php）。

因此，启用 Gii 的本质就是在应用的modules配置属性中注册一个名为gii、类为yii\gii\Module的模块。从Module::setModule()的实现可以看到，模块配置会被登记到模块容器中，并在首次访问时被实例化。

说明：本指南面向"基本应用模板（Basic）"的使用方式，高级模板（Advanced）中的backend与frontend应用启用方式相同，只是配置文件路径不同（如backend/config/main.php）。

启用 Gii：配置、入口脚本与环境常量

在 config/web.php 中注册模块

无论应用是通过何种方式创建的，启用 Gii 的配置代码通常已经存在于config/web.php中，标准写法如下：

$config = [ ... ]; if (YII_ENV_DEV) { $config['bootstrap'][] = 'gii'; $config['modules']['gii'] = [ 'class' => 'yii\gii\Module', ]; }

这段配置的含义是：当应用处于开发环境时：

• $config['modules']['gii']声明应用包含一个名为gii的模块，其类为yii\gii\Module；
• $config['bootstrap'][] = 'gii'将gii加入引导（bootstrap）列表，使模块在应用启动阶段就被加载。

bootstrap机制的具体执行可以在框架源码中找到。在yii\base\Application::bootstrap()中，框架遍历$this->bootstrap数组中的每一项：如果该项是字符串，则先判断它是已注册的组件（$this->has($mixed)）还是模块（$this->hasModule($mixed)），若是模块则通过$this->getModule($mixed)实例化并加载它。这正是 Gii 的控制器路由能够在应用启动后立即可用的原因——模块在引导阶段就被提前实例化，其路由规则随之注册进应用。

入口脚本决定开发环境

YII_ENV_DEV之所以为真，取决于入口脚本web/index.php中定义的环境常量。检查你的web/index.php，通常会看到如下代码：

defined('YII_ENV') or define('YII_ENV', 'dev');

根据 docs/guide/concept-configurations.md#environment-constants 的说明，YII_ENV可取三个值：

入口脚本将YII_ENV定义为dev，应用即处于开发模式，YII_ENV_DEV求值为true，上面的条件配置随之生效，Gii 被自动启用。反过来，如果入口脚本未定义YII_ENV或定义为prod，Gii 模块将不会被注册——这本身就是一种基于环境常量的安全开关，避免生成器在生产环境暴露。

访问 Gii

配置就绪后，通过浏览器访问下面的 URL 即可打开 Gii 首页：

https://hostname/index.php?r=gii

URL 中的r参数即路由（route），gii是模块的唯一 ID（uniqueId）。从Module::getUniqueId()的实现可以看到，位于应用根部的模块其唯一 ID 就是自身的$id（gii），而嵌套子模块则会被拼接为父ID/子ID形式。

安全限制：allowedIPs 白名单

出于安全考虑，当你从 localhost 之外的机器访问 Gii 时，默认会被拒绝。此时需要为 Gii 配置允许访问的 IP 白名单：

'gii' => [ 'class' => 'yii\gii\Module', 'allowedIPs' => ['127.0.0.1', '::1', '192.168.0.*', '192.168.178.20'] // 按需调整 ],

其中127.0.0.1与::1分别代表 IPv4/IPv6 的本机回环地址，192.168.0.*使用通配符匹配整个子网，也可以像192.168.178.20一样精确到单个 IP。该配置应视为生产环境的安全红线：请勿在生产环境中启用 Gii，即便启用也务必收紧白名单。

用 Model Generator 生成 Active Record 类

填写生成表单

在 Gii 首页点击Model Generator（模型生成器）链接，进入表单后按如下填写（以指南示例中的country表为例）：

• Table Name：country
• Model Class：Country

Model Generator 的作用是为指定的数据库表生成对应的模型类。生成出的类继承自框架的yii\db\ActiveRecord基类，从而获得按主键查询、关联查询、插入、更新、删除等 Active Record 的全部能力，同时根据表结构自动推导属性标签（labels）与验证规则（rules）。

预览、diff 与覆盖生成

填写完毕后点击Preview（预览）按钮，Gii 会列出将要生成的文件，此时应能看到models/Country.php出现在待创建文件列表中。可以点击该文件名直接预览将要生成的代码内容。

Gii 的预览环节提供了两个关键能力：

• diff 对比：如果你此前已经创建过同名文件，点击文件名旁的diff按钮，Gii 会显示"将要生成的代码"与"现有文件"之间的差异，帮助你判断是否值得覆盖；
• overwrite 覆盖：需要覆盖已有文件时，勾选文件旁的overwrite复选框，再点击Generate（生成）按钮；若是全新文件，直接点击Generate即可。

生成结束后，Gii 会显示确认页面，提示代码已成功生成；如果覆盖了已有文件，还会同时显示该文件已被新代码覆盖的提示。

用 CRUD Generator 生成完整增删改查

CRUD 是 Create（创建）、Read（读取）、Update（更新）、Delete（删除）四个单词的缩写，对应绝大多数网站对数据执行的四类常规操作。Gii 的CRUD Generator（CRUD 生成器）能够一次性生成控制器、模型、搜索模型与视图，完整实现这四类功能。

在 Gii 首页点击CRUD Generator，以country为例填写如下字段：

• Model Class：app\models\Country
• Search Model Class：app\models\CountrySearch
• Controller Class：app\controllers\CountryController

其中CountrySearch是 Gii 同步生成的"搜索模型"，它基于yii\data\ActiveDataProvider实现数据网格的过滤、排序与分页查询逻辑，供列表页使用；若希望深入研究其原理，可参见 docs/guide/output-data-providers.md 对数据提供者的讲解。

点击Preview后，Gii 会列出将要生成的完整文件清单：

如果你在指南的"数据库"章节中已经手工创建过controllers/CountryController.php与views/country/index.php这两个文件（此前版本未完整支持 CRUD 功能），请勾选overwrite复选框，让 Gii 用完整支持 CRUD 的新版本覆盖它们。

试运行：验证生成的 CRUD 页面

生成完成后，在浏览器中访问以下 URL 查看效果：

https://hostname/index.php?r=country/index

页面会展示一个数据网格，列出数据库表中所有国家记录。你可以：

• 排序：点击网格列头对数据进行排序；
• 过滤：在列头的输入框中输入过滤条件并提交，网格会按条件筛选数据。

对网格中的每一行，你都可以执行三类操作：查看详情（View）、更新（Update）、删除（Delete）。此外，网格顶部的Create Country按钮会引导你进入一个创建新国家的表单页面。

至此，一条完整的数据操作链路——创建、列表展示（含搜索过滤）、详情、更新、删除——已经全部由 Gii 自动生成并可直接运行。

生成的文件清单

以下是 Gii 为country示例生成的全部文件，也是后续排查与定制的落脚点：

• 控制器：controllers/CountryController.php
• 模型：models/Country.php与models/CountrySearch.php
• 视图：views/country/*.php（index、view、create、update、_form 等视图文件）

以仓库中的真实应用模板结构为参照，这些文件分别落在应用根目录的controllers/、models/、views/三个目录下，遵循 Yii 2 标准的 MVC 目录约定（参见 docs/guide/structure-overview.md 对整体目录结构的说明）。

定制与扩展生成代码

Gii 被设计为一个高度可定制、可扩展的代码生成工具（yii\gii\Module本身即支持通过模块配置注入自定义生成器）。合理的定制策略包括：

• 直接修改生成后的文件：Gii 生成的代码是普通 PHP 文件，与手写代码无任何区别，你可以自由调整控制器动作、验证规则、视图布局与样式；
• 重复生成并谨慎覆盖：数据表结构变化后，可再次进入 Gii 重新生成，利用Preview + diff功能先对比差异，再决定是否覆盖，避免误伤手写改动；
• 扩展生成器：从源码结构看，Gii 以生成器（Generator）为核心抽象，每个生成器对应一个表单与一组模板文件，开发者可以基于此添加自定义生成器，将其注册到 Gii 模块中供团队复用。

需要提醒的是：覆盖生成会用新代码整体替换旧文件，因此对生成文件做过的手工修改在覆盖后会丢失。建议将固定不变的定制逻辑抽离到 trait、行为（behavior）或独立基类中，再让生成类继承，从而兼顾"重复生成"与"保留定制"。

总结

通过本指南，你完成了从启用 Gii 到生成完整 CRUD 功能的全部闭环：

1. 在config/web.php中通过modules配置注册yii\gii\Module，并由入口脚本的环境常量驱动其按环境启停；
2. 使用Model Generator为country表生成基于yii\db\ActiveRecord的模型类，掌握 Preview、diff、overwrite 的生成流程；
3. 使用CRUD Generator一键生成控制器、搜索模型与全部视图，实现创建、读取、更新、删除的完整数据操作；
4. 在浏览器中验证数据网格的排序、过滤、增删改能力，并基于生成文件清单进行后续定制。

在此基础上，Gii 所代表的"以表单驱动、以模板生成、以差异预览保护手写代码"的工作方式，可以显著加速数据库驱动功能的开发节奏——它生成的是可运行的起点，而非不可修改的终点。

• 后端
• Web框架