企业官网建设流程全解析

InnoShop 是基于 Laravel 的开源 AI 电商系统，它的两大底层设计是Repository 仓储模式与Translatable 多语言模型。前者让所有数据的增删改查都经过统一的"数据仓库"，后者让商品、分类、文章等 13 种模型开箱即用地支持多语言。这篇指南带你快速看懂这两个机制的真实实现原理。

一、为什么需要 Repository 仓储模式

在 Laravel 项目里，初学者习惯在控制器中直接写Category::where(...)这类查询。当业务变复杂后，数据库操作散落在各处，难以维护。

InnoShop 的解法是：控制器只调用 Repository，不直接操作 Model。

• 所有数据访问都封装在 Repositories/ 目录下，共 60 多个仓库类，如 CategoryRepo.php、ProductRepo.php
• 控制器示例：CategoryController.php 中只用了一行CategoryRepo::getInstance()->all($filters)就取回分类列表

这种分层带来了三个好处：查询逻辑可复用、多语言/关联预加载统一处理、数据库表结构变化时只需改一处。

二、BaseRepo：一套模板搞定 80% 的数据操作

所有仓库类都继承自 BaseRepo.php，并遵循统一接口 RepoInterface.php。它提供了 CRUD 的完整标准方法：

最巧妙的设计是"模型自动发现"（见 BaseRepo.php）：构造函数通过命名约定自动找到对应 Model——把类名CategoryRepo中的Repo去掉、Repositories替换成Models，就得到了InnoShop\Common\Models\Category。只要命名规范，新增一个实体几乎不需要额外配置。

此外还提供链式工具：

• withActive()：只查启用中的数据
• withRelations([...])：批量预加载关联，避免 N+1 查询

三、CategoryRepo：仓储模式的多语言实战

基础模板解决了通用问题，各仓库类再覆盖builder()、create()等方法注入业务逻辑。以 CategoryRepo.php 为例：

1. 统一预加载翻译

覆盖后的 builder() 一次性预加载translation、children.translation等关联，保证无论列表页还是详情页，分类名称都不会出现重复查询。

2. 事务化写入多语言数据

createOrUpdate() 在数据库事务中同时保存主表和翻译表，任何一步失败整体回滚，保证数据一致。

3. 支持 REST PATCH 部分更新

patch() 会把已存在的翻译按locale合并后再落库，方便 API 调用方只提交改动的语言字段。

四、Translatable 多语言模型：一张独立翻译表解决所有语言

1. 表结构设计

InnoShop 没有使用 JSON 字段存翻译，而是给每个多语言实体配一张独立翻译表。以文章为例，主表articles存 slug、排序等通用字段，翻译数据存到article_translations，结构定义见 2024_04_01_161034_init_innoshop_table.php：

对应 Eloquent 模型 Article/Translation.php 只需声明表名和可填字段即可。

2. 一个 Trait 让 Model 拥有多语言超能力

Translatable.php 是一个只有 90 多行的 Trait，Product、Category、Article、Brand、Tag等13 个模型都复用了它（如 Article.php 中的use Translatable）。它提供 4 个核心能力：

1. translations：一对多关联，取出该记录的所有语言版本；
2. translation：只取当前语言的一条，依据 locale_code()——后台取管理员语言，前台取 session 中的语言；
3. translate($locale, $field)：指定任意语言取指定字段；
4. fallbackName()：三级降级策略——当前语言 → 系统默认语言 → 任意已存在的语言，保证前台永远不会显示空标题（见 Translatable.php）。

3. 访问器让业务代码"无感"取译文

以 Article.php 为例，getTitleAttribute()内部调用fallbackName('title')。于是业务代码里写$article->title就像访问普通字段一样简单，语言切换逻辑完全被隐藏在 Model 层。

五、TranslationHandler：翻译写入前的"智能加工"

翻译数据入库前还要经过 TranslationHandler.php 处理，它是仓储层与多语言表之间的"胶水"：

• 语言过滤：跳过未启用的语言代码；
• HTML 净化：防止富文本中夹带恶意脚本；
• 自动填充（auto_fill_lang）：某语言的字段留空时，自动用默认语言的内容补齐；
• TDK 联动（title_to_tdk）：标题填写后，自动同步到meta_title、meta_description、meta_keywords，SEO 字段一次搞定。

这两个开关在后台系统设置中即可控制，无需改代码。

六、总结：两大模式如何协作

一句话概括：Repository 管"怎么存、怎么查"，Translatable 管"怎么读对语言"，两者配合让 InnoShop 的多语言多货币能力开箱即用。想深入源码，推荐从 innopacks/common/src/ 目录入手阅读。