如何设计「AI 可读」的 Laravel + Livewire 后台架构

当 AI 开始参与写代码、改代码、生成模块时，
**“能不能跑”已经不重要了，
“能不能被 AI 理解”才是决定效率上限的关键。**

在实践 Laravel 12 + Livewire 4 构建Teanary[ https://gitee.com/teanary/teanary_service ]后台的过程中，我们逐渐意识到：
传统“人类可读”的代码结构，并不等于“AI 可读”。

本文将从架构、命名、分层、组件设计等角度，总结一套专门为 AI 协作优化的后台设计方法。

一、什么是「AI 可读」架构？

先说结论：

AI 可读 ≠ 注释多 ≠ 文档厚
AI 可读 = 结构自解释 + 意图明确 + 低歧义

AI 在读代码时，最怕什么？

业务逻辑散落在多个层
同一个概念有 3 种名字
Controller / Component 又厚又杂
隐式魔法太多（Hook、动态行为）
“这个东西是干嘛的？”需要上下文推理

而 Laravel + Livewire 天然具备被 AI 理解的潜力，前提是：
👉 你别把它写乱了

二、核心原则一：页面 = 用例（Use Case）

❌ 传统写法（AI 极难理解）

UserController
UserService
UserRepository
UserTransformer
UserApiController
UserPageController

AI 会直接懵：

“你到底想干嘛？”

✅ AI 友好写法：以「页面 / 用例」为核心

app/
 └── Livewire/
     └── Users/
         ├── UserList.php        // 用户列表
         ├── CreateUser.php      // 创建用户
         ├── EditUser.php        // 编辑用户
         └── UserDetail.php      // 用户详情

一个 Livewire Component = 一个明确的业务用例

AI 非常擅长理解这种结构，因为：

文件名就是意图
没有“抽象猜谜”
一个组件 ≈ 一个需求描述

三、核心原则二：组件必须「单一职责到极致」

AI 最擅长什么？

👉 在“局部、封闭、明确”的上下文中生成正确代码

所以你要反过来设计组件：

❌ 错误示例（人类都难维护）

class UserManager extends Component
{
    // 列表
    // 搜索
    // 编辑
    // 删除
    // 批量操作
    // 弹窗
}

✅ AI 友好示例

UserTable        // 只负责展示列表
CreateUserForm   // 只负责创建
EditUserForm     // 只负责编辑
DeleteUserAction // 只负责删除行为

AI 能做到的前提是：

你不要让它一次“理解整个系统”

四、核心原则三：命名 = 给 AI 的 Prompt

这是最重要的一点。

1️⃣ 方法名必须是「动作 + 业务对象」

// 好
createUser()
updateUser()
disableUser()
assignRoleToUser()

// 坏
handleSubmit()
process()
action()
save()

AI 生成代码时，本质就是在做语义补全。
模糊命名 = 错误补全。

2️⃣ Livewire 属性必须是“状态描述”

public bool $showCreateModal = false;
public string $searchKeyword = '';
public ?User $editingUser = null;

而不是：

public $flag;
public $data;
public $value;

👉 属性名就是 UI 状态说明书

五、核心原则四：业务逻辑“下沉但不分裂”

这是很多人写坏 Laravel 的地方。

❌ 反 AI 的写法

Controller 一点
Service 一点
Trait 再一点
Helper 偷偷来一点

AI 会直接失去全局一致性。

✅ 推荐做法：Use Case / Action 类

app/
 └── Actions/
     └── User/
         ├── CreateUser.php
         ├── UpdateUser.php
         └── DeleteUser.php

class CreateUser
{
    public function execute(array $data): User
    {
        // 完整、封闭、可测试
    }
}

Livewire 中：

public function create()
{
    app(CreateUser::class)->execute($this->form);
}

AI 极其擅长补全 Action 类，因为：

输入清晰
输出明确
无 UI 干扰

六、核心原则五：显式 > 隐式（为 AI 放弃一部分“优雅”）

Laravel 很多“优雅写法”对 AI 是毒药

❌ 例子

User::active()->recent()->visible()->get();

AI 不知道：

active 是什么
visible 规则在哪
是否有副作用

✅ AI 友好写法

User::query()
    ->where('status', UserStatus::ACTIVE)
    ->where('is_visible', true)
    ->orderByDesc('created_at')
    ->get();

👉 明确永远比“聪明”重要

七、核心原则六：注释是“业务说明”，不是翻译代码

❌ 无效注释

// update user
public function updateUser() {}

✅ AI 有用的注释

/**
 * 更新用户基础信息
 * - 不允许修改邮箱
 * - 超级管理员不可被禁用
 */
public function updateUser() {}

AI 会把这些当成规则约束，而不是废话。

八、Livewire + AI 的理想协作模式

当你做到以上几点后，你会发现：

AI 可以直接：
- 生成 Livewire 组件
- 拆分复杂组件
- 补全 Action 类
- 修改 UI 状态逻辑
人类只需要：
- 定义业务边界
- 审核规则是否正确

这就是“AI-first 后台架构”的真正价值。

九、终极判断标准：一句话能不能描述这个文件？

如果你能对 AI 说：

“这是一个用于【创建租户用户】的 Livewire 组件”

而 AI 打开文件后发现：

命名一致
职责单一
逻辑闭合

那你这套架构，已经是 AI 可读的了。

十、总结：这是在为未来 3–5 年写代码

AI 不会取代你，但：

会取代那些“写给自己看”的代码结构

Laravel + Livewire 本身已经站在正确方向上了，
剩下的差距，只在你是否愿意为“可理解性”让路。

如何设计「AI 可读」的 Laravel + Livewire 后台架构