禅道二次开发实战：从零构建自定义字段模块

最新推荐文章于 2026-04-02 09:47:25 发布

原创

最新推荐文章于 2026-04-02 09:47:25 发布 · 107 阅读

标签

#禅道 #二次开发 #zentaoPHP #扩展机制

1. 为什么我们需要自定义字段？从“测试方式”说起

大家好，我是老张，在软件开发和项目管理工具这块摸爬滚打了十几年，用过不少工具，也踩过不少坑。今天想和大家聊聊禅道的二次开发，特别是怎么给它加个自定义字段。你可能觉得，禅道功能已经很全了，为什么还要折腾二次开发？我举个真实的例子你就明白了。

我们团队之前用禅道管理测试用例，用例有优先级、类型、状态，但就是缺一个“测试方式”的标记。简单说，就是没法一眼看出这个用例是准备用手工测，还是用自动化脚本跑。每次测试执行前，都得人工去翻看用例标题或者备注，效率很低，还容易出错。测试经理想统计自动化用例的覆盖率，也得一个个手动筛选，非常麻烦。这时候，给测试用例模块加一个“测试方式”的字段，就成了刚需。选项很简单，就“手工”和“自动化”两种。这个需求听起来不复杂，对吧？但如果你不熟悉禅道的扩展机制，可能连从哪儿下手都不知道。

别担心，今天我就手把手带你，从零开始，为禅道测试用例模块打造一个“测试方式”自定义字段。整个过程就像搭积木，我们会一步步拆解，从怎么找到要改的代码位置，到怎么改前端页面、加语言包、写后端逻辑，最后怎么在数据库里存这个新字段。我会把我踩过的坑、总结的技巧都分享出来，保证你跟着做一遍就能掌握。咱们不搞那些虚头巴脑的理论，直接上实战。你不需要把整个ZentaoPHP框架吃透，跟着我的节奏，在动手的过程中学习，是最快的方式。

注意：本文的实战基于禅道开源版16.4。需要提醒的是，禅道在16.5及之后的版本中，对扩展机制做了优化和调整，如果你用的是更新版本，建议先查阅官方开发文档，但核心思想和路径定位方法依然是相通的。

2. 动手前的准备：找准“手术刀”下刀的位置

做二次开发，最怕的就是一头扎进代码海洋里找不到北。我的经验是，先别急着写代码，花点时间“侦查”清楚目标在哪里。这个过程，我称之为“定位模块”，这是所有后续操作的地基，地基打歪了，后面全白搭。

怎么定位呢？最直接的方法就是看浏览器的地址栏。比如，我们要改的是“新建测试用例”的页面。你登录禅道，点开“测试”->“用例”->“建用例”，这时候浏览器的URL通常会显示类似 http://你的禅道地址/zentao/testcase-create-1.html 这样的结构。这个URL就是我们的“藏宝图”。它明确告诉我们几个关键信息：testcase 是模块名，create 是方法名。后面跟着的 1 之类的数字是参数，通常是产品ID，这个我们暂时不用深究。

有了模块名和方法名，我们就可以按图索骥找到禅道源码里的对应文件了。禅道的MVC结构比较清晰：

Control层（控制器）：文件路径是 /module/testcase/control.php。里面的 create 方法负责处理页面逻辑，准备数据给前端。
View层（视图）：文件路径是 /module/testcase/view/create.html.php。这就是我们在浏览器里看到的那个表单页面的HTML模板。
Model层（模型）：文件路径是 /module/testcase/model.php。它负责和数据库 zt_case（用例表）打交道，所有数据的增删改查逻辑都在这里。

搞清楚这个关系，我们心里就有谱了。我们要做的“测试方式”字段，需要在这三个地方都留下足迹：View层要画出这个下拉框，Control层要给它准备初始值和选项列表，Model层要在保存数据时，把这个字段的值存进数据库。不过，禅道强大的地方在于，它提供了非侵入式的扩展机制，我们不需要直接去修改这些核心文件，而是在它们旁边建立一个“扩展区”（ext目录）来写我们的代码，这样既安全，又便于后续升级。

3. 构建扩展模块：一步步搭建我们的新功能

好了，地图有了，现在开始动工。我们所有的扩展代码，都会放在 /module/testcase/ext/ 这个目录下。记住这个原则：绝不直接修改核心文件，所有改动都在 ext 目录里进行。这样禅道升级时，我们的扩展代码有很大概率能保留下来。

3.1 第一步：让页面“长”出新字段（View层扩展）

用户最先接触的是界面。我们要在新建用例的表单里，加入一个“测试方式”的下拉选择框。禅道提供了两种扩展View的方式：覆盖扩展和钩子扩展。我建议新手先从覆盖扩展入手，它更直观。

所谓覆盖扩展，就是“重写”整个页面模板。我们在 /module/testcase/ext/view/ 目录下，新建一个文件，名字必须和原模板文件一模一样，也就是 create.html.php。然后，我们需要把原文件 /module/testcase/view/create.html.php 的代码完整复制过来，再在合适的位置插入我们的新字段。

原文件代码很长，我们不需要全部理解，关键是找到其他字段是怎么写的，然后“依葫芦画瓢”。比如，我想把“测试方式”放在“适用阶段”后面。那我就先找