Inertia Rails 最佳实践
这是一份全面指南，介绍如何使用 Ruby on Rails 构建高质量的 Inertia.js 应用。本指南涵盖 8 个类别中的 50 多条规则，并根据对应用质量、性能和可维护性的影响进行优先级排序。
何时使用本指南
- 编写新的 Inertia Rails 控制器或页面
- 审查现有的 Inertia Rails 代码
- 重构 Rails 应用以使用 Inertia
- 优化 Inertia 应用的性能
- 实现身份验证／授权模式
- 构建带验证的表单
- 为 Inertia 响应设置测试
类别概览
快速参考
服务端设置与配置（CRITICAL）
| ID | 规则 | 适用场景 |
|---|
| setup-01 | 使用 Rails 生成器进行初始设置 | 新项目 |
| setup-02 | 配置资源版本控制以使缓存失效 | 所有项目 |
| setup-03 | 设置恰当的布局继承 | 多布局应用 |
| setup-04 | 合理配置 flash 键 | Flash 消息 |
| setup-05 | 使用环境变量进行配置 | 部署 |
| setup-06 | 周全地设置默认渲染行为 | 约定优于配置 |
Props 与数据管理（CRITICAL）
| ID | 规则 | 适用场景 |
|---|
| props-01 | Props 中仅返回必要数据 | 所有响应 |
| props-02 | 使用共享数据提供全局 Props | 身份验证、设置 |
| props-03 | 使用 lambda 实现延迟求值 | 开销较大的操作 |
| props-04 | 对非关键数据使用延迟 Props | 性能 |
| props-05 | 正确实现部分重新加载 | 刷新数据 |
| props-06 | 绝不在 Props 中暴露敏感数据 | 安全性 |
| props-07 | 使用 as_json 进行正确序列化 | 数据格式化 |
| props-08 | 在适当情况下实现深度合并 | 嵌套数据 |
| props-09 | 对稳定数据使用 once Props | 导航性能 |
| props-10 | 使用 Props 转换器统一命名 | camelCase 转换 |
表单与验证（HIGH）
| ID | 规则 | 适用场景 |
|---|
| forms-01 | 复杂表单使用 useForm 辅助函数 | 程序化控制 |
| forms-02 | 简单表单使用 Form 组件 | 声明式表单 |
| forms-03 | 正确处理验证错误 | 用户反馈 |
| forms-04 | 多个表单使用错误包 | 多表单页面 |
| forms-05 | 表单提交后使用重定向模式 | PRG 模式 |
| forms-06 | 正确处理文件上传 | Multipart 表单 |
| forms-07 | 验证错误出现时保留表单状态 | 用户体验 |
| forms-08 | 嵌套数据使用点号表示法 | 复杂表单 |
| forms-09 | 使用预检功能进行实时验证 | 服务端验证 |
| forms-10 | 非导航请求使用 useHttp | API 调用 |
导航与路由（高）
| ID | 规则 | 上下文 |
|---|
| nav-01 | 使用 Link 组件进行内部导航 | SPA 行为 |
| nav-02 | 使用 inertia_location 进行外部重定向 | 外部 URL |
| nav-03 | 适当实现 preserve-scroll | 滚动位置 |
| nav-04 | 使用 preserve-state 保留组件状态 | 表单保留 |
| nav-05 | 为链接配置适当的 HTTP 方法 | RESTful 操作 |
| nav-06 | 对静态页面使用 inertia 路由辅助工具 | 简单路由 |
| nav-07 | 正确处理 303 重定向 | POST/PUT/PATCH/DELETE |
| nav-08 | 使用即时访问提升感知性能 | 快速导航 |
性能优化（中高）
| ID | 规则 | 上下文 |
|---|
| perf-01 | 使用动态导入实现代码拆分 | 包大小 |
| perf-02 | 为可能的导航使用预取 | 感知性能 |
| perf-03 | 配置 stale-while-revalidate 缓存 | 数据新鲜度 |
| perf-04 | 仅在必要时使用轮询 | 实时更新 |
| perf-05 | 使用 merge props 实现无限滚动 | 大型数据集 |
| perf-06 | 优化进度指示器 | 用户反馈 |
| perf-07 | 对非阻塞操作使用异步访问 | 后台任务 |
| perf-08 | 使用 InfiniteScroll 组件进行分页 | 大型数据集 |
| perf-09 | 启用视图过渡，实现流畅动画 | 页面过渡 |
安全（中高）
| ID | 规则 | 上下文 |
|---|
| sec-01 | 在服务端实现身份验证 | 身份验证模式 |
| sec-02 | 将授权结果作为 props 传递 | 权限检查 |
| sec-03 | 对敏感数据使用历史记录加密 | 浏览器历史记录 |
| sec-04 | 使用 Rails CSRF 保护 | 表单安全 |
| sec-05 | 在服务端验证并清理所有输入 | 数据验证 |
| sec-06 | 在控制器中使用强参数 | 批量赋值 |
测试（中）
| ID | 规则 | 上下文 |
|---|
| test-01 | 使用 RSpec 匹配器测试 Inertia 响应 | RSpec 测试 |
| test-02 | 使用 Minitest 断言测试 Inertia | Minitest 测试 |
| test-03 | 测试部分重新加载和延迟 props | 高级功能 |
| test-04 | 使用 Capybara 实现端到端测试 | 集成测试 |
| test-05 | 测试重定向后的 flash 消息 | Flash 测试 |
| test-06 | 验证组件渲染 | 响应验证 |
高级模式（中）
| ID | 规则 | 上下文 |
|---|
| adv-01 | 实现持久布局 | 状态保留 |
| adv-02 | 使用自定义组件路径解析器 | 非标准路径 |
| adv-03 | 配置 prop 转换器 | 数据转换 |
| adv-04 | 适当处理 SSR | SEO 要求 |
| adv-05 | 实现视图过渡 | 现代动画 |
| adv-06 | 对复杂布局使用滚动区域 | 滚动管理 |
| adv-07 | 有效处理事件系统 | 生命周期钩子 |
| adv-08 | 使用布局 props 在页面与布局之间传递数据 | 布局数据 |
| adv-09 | 配置 Vite 插件以优化开发体验 | 项目设置 |
有关每条规则的详细说明、代码示例和实现指南，请参阅 AGENTS.md。
