作为 TYPO3 的开发我第一次听到“t3code”这个代号是在我们决定把客户项目从“一次性交付代码”重构为“可复用业务底座”的那天。t3 是这个圈子里默认的缩写code 则是我们真正要交付的东西——一套能跑、能扩展、能测试的代码资产。这个计划听起来不复杂但落到目录结构、Composer 包、TCA 设计、测试策略和团队协作上时牵扯出来的细节远比想象中多。这篇文章想原原本本把 t3code 怎么起底、怎么落地、怎么踩坑整理出来适合正在做 TYPO3 扩展开发、或者准备把多个客户项目统一基础能力的开发者和团队参考。1. 拆解项目t3code 到底在做什么1.1 为什么先有代码命名后有业务功能很多团队启动新项目时会先谈功能列表、页面设计、数据库表但我们这次是先定代码资产的边界。t3code 不是一个单一功能模块而是一个覆盖三层内容的工程代号最底层是可复用的基础扩展用来放公共的控制器基类、通用数据模型和统一的服务配置中间层是面向具体业务域的扩展包比如客户管理、订单查询、表单提交最上层则是构建脚本和代码质量配置保证不管哪个成员接手跑出来的代码风格和测试结果都一致。这种先定代码边界的做法解决的是 TYPO3 项目里最常见的一个问题同一个页面模板里有几十个字段同一个表单逻辑被复制粘贴到五个扩展里改一个字段名要全局搜索半天。把 t3code 作为统一的项目代号和命名空间前缀一开始就给所有成员建立了一个清晰的“什么东西放在哪里”的秩序。代码命名不只是给人看的更是给依赖分析、自动加载和后续升级测试用的。1.2 t3code 的适用场景与目标读者如果你只是做一个展示型的企业官网只有几个内容页和一个联系表单那直接安装几个现成扩展、在模板里配置一下就够了完全不需要搞一套 t3code 这样的工程体系。但如果你手里握着一类需要重复交付的业务系统——比如给不同客户做会员中心、服务预约、数据报表每次都是从零复制代码再改字段那 t3code 这套做法就非常合适。适合读这篇文章的人我认为有三类第一类是 TYPO3 的集成商团队正在寻找统一团队代码风格和交付节奏的方法第二类是已有 TYPO3 基础、想进阶学习扩展开发规范的开发者比如想知道 composer.json 里每个字段为什么这么写、TCA 为什么这样组织第三类是技术负责人需要评估在多个项目间建立共享库的可行性和成本。本文会涉及到实际命令、代码和配置但对纯业务人员来说重点看第一部分和最后一部分的设计思路就够了。1.3 方案选型为什么选 TYPO3 而不是自研框架把 t3code 放在 TYPO3 体系里实现而不是自己写一套 PHP 框架核心原因有两个。第一是 TYPO3 已经替我们解决了内容管理、权限系统、后端界面、多语言、缓存控制这些通用问题业务代码只需要关注领域逻辑不需要造轮子。第二是 TYPO3 的 Composer 机制对代码复用非常友好扩展可以被不同的根项目通过 Composer 引入依赖关系和版本约束都可以在 composer.json 里声明天然适合做“一处开发、多处部署”。自研框架可能让人觉得更“自由”但代价是必须自己维护认证、路由、数据库抽象、内容存储的后台界面这些工作的体量往往比业务功能本身还大。t3code 选择了在 TYPO3 的约束里做设计换来的是一套成熟平台提供的安全补丁、社区文档和大量现成接口。想清楚这一点后续的每次技术选型都会顺畅很多——凡是我发现自己在 TYPO3 体系里硬写一套重复能力时都会停下来问自己是不是没找到官方已经提供的正确入口。2. 从零搭建 t3code 的目录与配置2.1 标准目录结构设计项目落地时我们用了标准的多扩展仓库结构每个业务模块都是独立的 TYPO3 扩展包共享部分放进 base 扩展。一个典型的 t3code 工作区长这样t3code-workspace/ ├── composer.json ├── config/ │ └── system/ ├── packages/ │ ├── base/ │ │ ├── composer.json │ │ ├── ext_emconf.php │ │ ├── ext_localconf.php │ │ ├── ext_tables.php │ │ ├── Configuration/ │ │ │ ├── Services.yaml │ │ │ └── TCA/ │ │ ├── Classes/ │ │ │ ├── Controller/ │ │ │ ├── Domain/ │ │ │ ├── Middleware/ │ │ │ └── Utility/ │ │ └── Tests/ │ └── customers/ │ ├── composer.json │ ├── ext_emconf.php │ ├── ext_localconf.php │ ├── Configuration/ │ ├── Classes/ │ ├── Resources/ │ └── Tests/ └── build/ ├── phpstan.neon ├── php-cs-fixer.php └── rector.php这种结构的最大好处是base不依赖任何业务模块可以独立发版customers可以单独被某个站点启用或停用build目录里的静态分析配置不随着业务代码走整组项目共用一套标准。把测试文件夹Tests放在每个扩展包内部而不是集中在一处是因为我们在 CI 里需要对每个包单独跑测试这样职责足够清晰。2.2 composer.json 的配置细节每个 TYPO3 扩展的composer.json都是这套体系的灵魂。以 base 扩展为例我当时是这样写的{ name: t3code/base, description: Shared foundation layer for t3code projects, type: typo3-cms-extension, license: [proprietary], require: { php: 8.2, typo3/cms-core: ^12.4 || ^13.4, typo3/cms-extbase: ^12.4 || ^13.4, typo3/cms-fluid: ^12.4 || ^13.4 }, autoload: { psr-4: { T3code\\Base\\: Classes/ } }, autoload-dev: { psr-4: { T3code\\Base\\Tests\\: Tests/ } }, extra: { typo3/cms: { extension-key: base, cms-package: false } } }很多初写扩展的人会漏掉extra.typo3/cms.extension-key这个字段它告诉 TYPO3 这个 Composer 包对应的扩展键是什么。有了它扩展安装时系统才知道去哪里找ext_emconf.php、ext_localconf.php这些基础文件。cms-package字段则用来标记这个包不是 TYPO3 核心发行包避免安装器做多余的类型判断。require里我用的是^12.4 || ^13.4而不是写死^12.4这代表我们可以在 TYPO3 12 和 13 两个版本线上做兼容性开发。兼容两个大版本确实会增加工作量像是有些废弃方法在 13 里必须改掉但它换来的是客户站点的升级路径不被我们卡住。如果只是内部系统且不打算升级核心写死版本也没问题但我会建议至少留一个^的浮动空间给安全补丁留余地。2.3 入口文件的职责划分每次新建扩展都逃不开基础入口文件的配置ext_localconf.php、ext_tables.php、ext_emconf.php。它们的职责经常被混淆我吃过不少亏后总算理清了。ext_localconf.php负责的是扩展运行时的核心注册工作包括注册插件、挂载路由、配置后端模块、注册页面 TSconfig、定义依赖注入。ext_tables.php在 TYPO3 12 之后职责变轻了主要用于注册后端相关的内容比如自定义表单节点、页面模块图标传统意义上往 TCA 里增加列的工作现在已经挪到Configuration/TCA/Overrides下按表名命名文件来覆盖。ext_emconf.php是历史遗留格式但在不使用 TER 发布时依然会被系统读取用来读取扩展标题、版本号和依赖声明。t3code 的 base 扩展里我们是这么写的最小配置?php $EM_CONF[$_EXTKEY] [ title t3code Base, description Shared infrastructure for t3code projects., category misc, version 1.2.0, constraints [ depends [ typo3 12.4.0-13.4.99, ], ], ];如果你用 Composer 管理扩展ext_emconf.php里的版本号其实没那么重要真正生效的是 Composer 的版本约束。但很多旧版 TYPO3 管理接口、扩展管理器还会读取这个文件来做兼容性检查所以尽量保持它和composer.json的数据一致避免出现版本冲突的假警报。2.4 数据库 schema 与 TCA 设计要点领域模型一旦确定紧跟着要写的就是数据库 schema 和 TCA。t3code 里各个业务扩展的统一做法是数据库表先建在ext_tables.sql文件里TCA 定义放在Configuration/TCA覆盖逻辑放在Configuration/TCA/Overrides。一个适合的客户模块示例CREATE TABLE tx_customers_domain_model_customer ( uid int(11) NOT NULL auto_increment, pid int(11) DEFAULT 0 NOT NULL, tstamp int(11) DEFAULT 0 NOT NULL, crdate int(11) DEFAULT 0 NOT NULL, cruser_id int(11) DEFAULT 0 NOT NULL, deleted tinyint(4) DEFAULT 0 NOT NULL, hidden tinyint(4) DEFAULT 0 NOT NULL, name varchar(255) DEFAULT NOT NULL, email varchar(255) DEFAULT NOT NULL, phone varchar(64) DEFAULT NOT NULL, company varchar(255) DEFAULT NOT NULL, categories int(11) DEFAULT 0 NOT NULL, PRIMARY KEY (uid), KEY parent (pid) );这里每张业务表都会带上uid、pid、tstamp、crdate、cruser_id、deleted、hidden这几个基础字段。deleted和hidden走的是 TYPO3 软删除和隐藏机制让数据在界面层看起来被删了实际记录还在方便审计和恢复。对字段categories我当时的设计是让它存一个 uid再用逗号分隔存储多个关联 id如果你用的是 TYPO3 13 的新 persistencelayer则更推荐用中间表处理多对多关系字段设计要配合好查找路径。这个取舍在基础字段配置阶段想清楚后面写 Repository 查询会省很多事。3. 核心业务模块实现实录3.1 本地开发环境准备t3code 从开发的第一天起就建立了一个可复现的本地环境这是确保每个成员看到的代码行为一致的前提。我们用 DDEV 作为容器化开发环境它直接能生成 TYPO3 项目然后通过 Composer path repository 链接到 t3code 的本地包。composer.json里是这样关联{ repositories: [ { type: path, url: packages/*, options: { symlink: true, versions: { t3code/base: dev-main, t3code/customers: dev-main } } } ], require: { t3code/base: dev, t3code/customers: dev } }用path仓库加symlink: true代码修改立即可见不需要每次改动后重新composer update。我把这个关联配置放在根项目的composer.json里而不是每个扩展包里原因很简单本地开发时希望直接看最新源码但生产构建时要用发布的稳定版本这样根项目控制版本来源灵活性最好。环境准备好后第一步就是跑到一个能出页面的状态。执行ddev composer install然后在 DDEV 里跑ddev typo3 install:setup \ --db-drivermysqli \ --db-hostdb \ --db-usernamedb \ --db-passworddb \ --db-namedb \ --admin-useradmin \ --admin-passwordpassword后端的默认路由往往需要你手工确认主要还是看模板里的page根节点和sys_template是否创建成功。很多人开发 TYPO3 扩展时第一反应是写代码我的经验是先确认环境能正常渲染一个最简单的页面再开始动业务逻辑因为 80% 的配置问题都会在你写第一行业务代码前暴露出来。3.2 领域模型与 Repository 实现t3code 的领域设计不追求花哨的 DDD 完整形态但保持了一个底线模型类只保存数据和规则仓储类负责查询控制器负责流程协调。这里直接看一个具体的客户模型?php declare(strict_types1); namespace T3code\Customers\Domain\Model; use TYPO3\CMS\Extbase\DomainObject\AbstractEntity; class Customer extends AbstractEntity { protected string $name ; protected string $email ; protected string $phone ; protected string $company ; public function getName(): string { return $this-name; } public function setName(string $name): void { $this-name $name; } // 其他属性的 getter/setter 类似为节省篇幅省略 public function getEmail(): string { return $this-email; } public function getCompany(): string { return $this-company; } }模型中每个字段都声明了默认值并且在 setter 中不做复杂校验只做类型约束。这是有意为之校验逻辑放错地方会让控制器变得很乱而把所有校验都放模型又会让模型变成上帝类。我们的约定是简单数据类型约束交给 PHP 类型系统跨字段的业务规则放在单独的 Validator 类里控制器在createAction中调用。Repository 继承 Extbase 自带的仓储基类大多数查询在父类方法上组合就够了?php declare(strict_types1); namespace T3code\Customers\Domain\Repository; use TYPO3\CMS\Extbase\Persistence\Repository; class CustomerRepository extends Repository { public function findBySearchString(string $search): array { $query $this-createQuery(); $constraints []; if ($search ! ) { $constraints[] $query-like(name, % . $search . %); $constraints[] $query-like(email, % . $search . %); } if ($constraints ! []) { $query-matching($query-logicalOr(...$constraints)); } return $query-execute()-toArray(); } }写 Repository 方法时有个我反复踩过的坑不要直接在里面调用$this-persistenceManager-persistAll()。否则在批量导入客户数据的场景里每条记录都强制写库性能会按数量级下降。保持仓储只负责查询和追加写入操作留给控制器或 Command 控制器统一处理这是 t3code 的基础守则之一。3.3 控制器与会话流程控制器层是前后端业务逻辑交汇的地方。我们为 t3code 定制了一个基础的AbstractController统一处理错误提示、转发逻辑和权限校验业务控制器继承这个基类。典型流程是这样的?php declare(strict_types1); namespace T3code\Customers\Controller; use Psr\Http\Message\ResponseInterface; use TYPO3\CMS\Extbase\Mvc\Controller\ActionController; use T3code\Customers\Domain\Model\Customer; use T3code\Customers\Domain\Repository\CustomerRepository; use TYPO3\CMS\Extbase\Persistence\PersistenceManagerInterface; class CustomerController extends ActionController { public function __construct( private readonly CustomerRepository $customerRepository, private readonly PersistenceManagerInterface $persistenceManager, ) {} public function listAction(): ResponseInterface { $customers $this-customerRepository-findAll(); $this-view-assign(customers, $customers); return $this-htmlResponse(); } public function showAction(Customer $customer): ResponseInterface { $this-view-assign(customer, $customer); return $this-htmlResponse(); } public function createAction(Customer $customer): ResponseInterface { $this-customerRepository-add($customer); $this-persistenceManager-persistAll(); $this-addFlashMessage( 客户已保存, 成功, \TYPO3\CMS\Core\Messaging\AbstractMessage::OK ); return $this-redirect(list); } }注意这里的构造函数依赖注入方式。T3code 系列扩展的 Services.yaml 会自动识别构造函数中的参数类型来完成注入不需要写多余的 getter 或 service tag。下面的配置只需要把命名空间映射声明一次# Configuration/Services.yaml services: _defaults: autowire: true autoconfigure: true T3code\Customers\: resource: ../Classes/*控制器里showAction(Customer $customer)这类参数绑定依赖 Extbase 的 Property Mapper 从请求参数里解析对象。这里最容易出的问题是表单字段与模型字段的映射不匹配尤其是在前端模板里用了{customer.name}但控制器参数名却叫$customerUid。保持字段命名一致能少排查很多诡异问题。3.4 后端模块注册与权限管理业务系统往往需要后端的自定义管理入口。t3code 客户模块挂在 TypoScript 之外直接在Configuration/Backend/Modules.php里注册一个后端模块?php return [ customers [ parent web, position [after web_info], access user,group, iconIdentifier module-customers, labels LLL:EXT:customers/Resources/Private/Language/locallang_mod.xlf, routes [ _default [ target T3code\Customers\Controller\Backend\CustomerController::class, ], ], moduleData [ listing true, ], ], ];模块权限通过access字段限定为后台登录用户和用户组但「哪些用户组能看」还需要在根用户组的 TSconfig 里限制类似# 在根页面 TSconfig 中 mod.customers { allowedTables tx_customers_domain_model_customer disallowedTables }这个双层权限设计经常被忽视注册模块时不限制用户组所有后台用户都会看到这个入口再加上 Root TSconfig 的mod配置才能真正控制访问粒度。测试时我一般用两个账号一个是管理员一个是普通 editor 用户分别检查入口可见性和数据操作范围。4. 测试、代码质量与排错实录4.1 静态分析工具的配置思路代码能跑通只是第一步t3code 团队目标是让代码在合并前被机器检查一遍。我们在 build 目录下放置了统一的 PHPStan 配置parameters: level: 5 paths: - ../packages/base/Classes - ../packages/customers/Classes tmpDir: /tmp/phpstan phpVersion: 80200 treatPhpDocTypesAsCertain: falsePHPStan level 5 是我们的折中选择level 4 检查不了常见的类型问题level 6 又会引入太多严格的联合类型注解检查让团队在业务代码上纠缠细节。对 TYPO3 扩展项目来说level 5 能在不强迫为每个方法写 PHPDoc 的前提下抓住大多数空指针风险和参数类型错误。代码风格方面我们用 PHP-CS-Fixer规则集基于 PSR-12再额外启用declare_strict_types、no_unused_imports、ordered_imports这些常用规则。Rector 则专门用来做版本升级时的自动迁移比如从 TYPO3 12 升 13 时旧的GeneralUtility::makeInstance注册方式能通过 Rector 规则批量改写。4.2 自动化测试怎么跑t3code 的单元测试是基于 TYPO3 提供的测试框架跑的。我每天在本地至少执行一次这套完整命令链。以 DDEV 环境为例ddev exec composer phpstan analyse -c build/phpstan.neon ddev exec composer cs-fixer check ddev exec vendor/bin/phpunit -c packages/customers/phpunit.xml.dist写模型和仓储测试时有个实用技巧不用真的连接数据库就能跑单元测试直接把模型实例化调用方法后断言属性值。但涉及 Repository 查询逻辑的测试我建议至少配置一个 SQLite 内存数据库做功能测试因为 Extbase 的 Query 语句翻译和表结构定义在纯 Mock 环境里根本测不出来。我们用的测试基类继承自TYPO3\TestingFramework\Core\Functional\FunctionalTestCase并在测试类里明确声明测试表protected array $testExtensionsToLoad [ typo3conf/ext/customers, ]; protected array $testPathsToBeAvailable [ typo3/sysext/core, typo3/sysext/backend, ];测试跑完后TCA 的修改和表结构创建都是自动完成的。实际运行中你会发现一个麻烦如果测试类太多每个测试类都要重新构建一套 TYPO3 容器速度会比较慢。我们的优化方法是给测试按扩展分组只有改到哪个模块才完整跑哪个模块的测试全量测试留给 CI 在夜间执行。4.3 典型问题排查表做 t3code 过程中我们断断续续遇到了一些看着奇怪、原因却很集中的问题下面整理成排查表现象最常见原因解决动作新表字段在后台不显示TCA 文件没被加载或表结构没更新检查Configuration/TCA文件名是否匹配表名在安装工具里执行数据库分析手动比较控制器 action 报 404插件页面没有正确挂载数据确认 TypoScript 中plugin.tx_customers设置存在页面模板里放入了正确的 content element仓储查询结果为空没有设置storagePid或查询条件与软删除字段冲突在 TypoScript 中配置plugin.tx_customers.persistence.storagePid同时检查查询是否遗漏deleted0条件模板修改模型字段后系统提示列不存在数据库结构未同步在安装工具或使用ddev typo3 database:updateschema更新数据库表结构后端模块入口不显示模块注册文件没被加载或权限组未配置检查Configuration/Backend/Modules.php和根页面 TSconfig 的mod权限页面缓存不更新缓存相关配置未正确声明页面未设置config.no_cache时需要靠 TYPO3 的缓存清理机制调试期先在 TypoScript 顶部临时禁用缓存这些问题的共性在于大多数都不是代码逻辑本身出错而是配置加载顺序或系统状态不一致。因此我们后来给每个新成员准备了一个“问题自查清单”从上往下按表格执行一圈80% 的沟通成本能直接省掉。4.4 避坑心得有些坑不是查文档就能避开的要靠实打实的现场积累。t3code 的开发过程中我有几条特别想说的经验。第一模板变量命名要和 TCA 字段名完全一致。有一次我们为了前端展示方便把模板里的变量从customer.company写成了customer.companyName结果后台能录入、数据库里有值前端页面就是渲染不出来。原因是 TYPO3 的 Fluid 变量映射对拼写很敏感而错误提示又不会直接报出来。这是所有初学者几乎都会踩一遍的点。第二调试时不要只盯着浏览器。把一个\TYPO3\CMS\Core\Utility\DebugUtility::debug($query-getSql())打出来看实际生成的 SQL往往比单纯看对象值更快找到问题所在。运行环境里看到的报错信息可能被包装层吞掉直接看底层 SQL 能绕过不少干扰。第三要在进入开发前就把ext_tables.sql的字段默认值想好。后期给已上线的表加字段特别是已有存量数据的表默认值没设对就可能导致接口读取不到合法数据。轻则数据兼容性问题重则把整个栏目页打挂这个风险一定要前期控制住。5. 打包、协作与长期维护经验5.1 版本号与变更记录管理t3code 系列扩展用语义化版本规则非常简单新增兼容能力时升 minor急修复 bug 或安全问题时升 patch破坏性变更或核心功能重构时升 major。对于依赖 t3code 的客户站点版本升级是很大的成本所以我们在每个扩展的 README 顶部都写明支持的最低 TYPO3 版本和 PHP 版本避免团队内部出现“明明在 8.2 环境跑着却引用了 PHP 8.3 才有的语法”这种低级问题。变更记录我们采用 Keep a Changelog 格式每个发布版本在CHANGELOG.md中记录新增、变更、移除和修复四项。刚开始团队成员觉得这很麻烦但上线两周后所有人就改变了想法——通过回顾变更记录判断一次升级的影响范围比读 Git log 再去猜改动意图要快得多。5.2 多环境部署注意事项不同的客户站点往往跑在不同的服务器组合上t3code 的发布流程中部署是重头戏。我们不在服务器上手工拉代码而是把每个扩展打包为独立的 Composer 包推到公司内部的 Packagist 镜像。客户项目的根composer.json锁定精确版本比如{ require: { t3code/base: ^1.2.0, t3code/customers: ^2.1.0 } }发布流程固定为本地验证 → CI 跑静态分析和测试 → 打 Git tag → 推到镜像仓库 → 客户项目执行composer update t3code/base --with-dependencies。这套流程最大的好处是每个环境拿到的代码都是同一个 tag不会再出现“本地能跑测试环境不能跑”的老大难问题。5.3 团队协作的命名与提交规范t3code 不只是一个技术仓库名它同时定义了团队协作的语言。目录命名统一小写加中划线类命名规范对照 PSR-4数据库表的命名以扩展键开头。提交信息按类型加前缀feat、fix、chore、docs、test。一开始团队里也有人不习惯这种“形式主义”但后来发现它能直接让代码评审的注意力集中在逻辑上而不是被到处乱起的变量名打断。代码评审的粒度也要控制。我们内部约定一次 PR 尽量只提交一个完整功能或者一个修复不能把静态分析工具的格式化改动和业务逻辑改动混在一起。尤其是在 Rector 自动迁移时哪怕改动了很多文件只要语义一致也是一个独立 PR。这样一旦出现问题回滚定位的成本会低很多。5.4 后续扩展路线建议t3code 这套骨架到目前为止已经稳定跑了一段时间后面我们规划了几条明确的扩展方向。一是加入更多常用业务域包比如订单、预约、内容审核二是把测试策略从单元测试为主转变成功能测试为主因为功能测试更能覆盖 TYPO3 整个请求生命周期三是尝试引入更细粒度的 Event 监听机制把业务模块做成完全解耦的发布订阅模式让客户可以在不修改核心扩展的情况下用自定义扩展覆盖默认行为。如果你也想在团队里开展类似 t3code 的工程整合我的建议是不要贪多先把一个最核心的业务模块完整地以“可复用包”的方式打磨出来跑通从开发、测试、发布、部署的整条链路。然后你会清楚知道哪些模式能复制哪些地方需要根据团队情况调整。没有一个统一方案能套在所有项目上但一套经过实战检验的工作流框架会比每次重新发明轮子节省大量时间。