inertia-rails-best-practices
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseInertia Rails Best Practices
Inertia Rails 最佳实践
A comprehensive guide to building high-quality Inertia.js applications with Ruby on Rails. This skill provides 50+ rules across 8 categories, prioritized by impact on application quality, performance, and maintainability.
这是一份使用Ruby on Rails构建高质量Inertia.js应用的综合指南。本技能涵盖8大分类下的50+条规则，根据对应用质量、性能和可维护性的影响程度进行优先级排序。
When to Use This Skill
适用场景
- Writing new Inertia Rails controllers or pages
- Reviewing existing Inertia Rails code
- Refactoring Rails applications to use Inertia
- Optimizing performance of Inertia applications
- Implementing authentication/authorization patterns
- Building forms with validation
- Setting up testing for Inertia responses
- 编写新的Inertia Rails控制器或页面
- 评审现有Inertia Rails代码
- 重构Rails应用以接入Inertia
- 优化Inertia应用的性能
- 实现认证/授权模式
- 构建带验证的表单
- 为Inertia响应设置测试
Categories Overview
分类概览
| # | Category | Priority | Impact |
|---|---|---|---|
| 1 | Server-Side Setup & Configuration | CRITICAL | Foundation for all Inertia functionality |
| 2 | Props & Data Management | CRITICAL | 2-5× performance improvement, security |
| 3 | Forms & Validation | HIGH | User experience, data integrity |
| 4 | Navigation & Routing | HIGH | SPA experience, performance |
| 5 | Performance Optimization | MEDIUM-HIGH | 30-70% faster page loads |
| 6 | Security | MEDIUM-HIGH | Protection against common vulnerabilities |
| 7 | Testing | MEDIUM | Code quality, maintainability |
| 8 | Advanced Patterns | MEDIUM | Scalability, complex use cases |
Quick Reference
快速参考
Server-Side Setup & Configuration (CRITICAL)
服务端配置与设置（关键）
| ID | Rule | Context |
|---|---|---|
| setup-01 | Use the Rails generator for initial setup | New projects |
| setup-02 | Configure asset versioning for cache busting | All projects |
| setup-03 | Set up proper layout inheritance | Multi-layout apps |
| setup-04 | Configure flash keys appropriately | Flash messaging |
| setup-05 | Use environment variables for configuration | Deployment |
| setup-06 | Set up default render behavior thoughtfully | Convention over configuration |
| ID | 规则 | 适用场景 |
|---|---|---|
| setup-01 | 使用Rails生成器完成初始配置 | 新项目 |
| setup-02 | 配置资源版本控制以实现缓存击穿 | 所有项目 |
| setup-03 | 配置正确的布局继承 | 多布局应用 |
| setup-04 | 合理配置flash键 | 消息提示 |
| setup-05 | 使用环境变量进行配置 | 部署场景 |
| setup-06 | 谨慎设置默认渲染行为 | 约定优于配置 |
Props & Data Management (CRITICAL)
Props与数据管理（关键）
| ID | Rule | Context |
|---|---|---|
| props-01 | Return only necessary data in props | All responses |
| props-02 | Use shared data for global props | Auth, settings |
| props-03 | Leverage lazy evaluation with lambdas | Expensive operations |
| props-04 | Use deferred props for non-critical data | Performance |
| props-05 | Implement partial reloads correctly | Data refreshing |
| props-06 | Never expose sensitive data in props | Security |
| props-07 | Use proper serialization with as_json | Data formatting |
| props-08 | Implement deep merge when appropriate | Nested data |
| props-09 | Use once props for stable data | Navigation performance |
| 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 | 为稳定数据使用一次性Props | 导航性能 |
Forms & Validation (HIGH)
表单与验证（高）
| ID | Rule | Context |
|---|---|---|
| forms-01 | Use useForm helper for complex forms | Programmatic control |
| forms-02 | Use Form component for simple forms | Declarative forms |
| forms-03 | Handle validation errors properly | User feedback |
| forms-04 | Implement error bags for multiple forms | Multi-form pages |
| forms-05 | Use redirect pattern after form submission | PRG pattern |
| forms-06 | Handle file uploads correctly | Multipart forms |
| forms-07 | Preserve form state on validation errors | User experience |
| forms-08 | Use dotted notation for nested data | Complex forms |
| ID | 规则 | 适用场景 |
|---|---|---|
| forms-01 | 为复杂表单使用useForm助手 | 程序化控制 |
| forms-02 | 为简单表单使用Form组件 | 声明式表单 |
| forms-03 | 正确处理验证错误 | 用户反馈 |
| forms-04 | 为多表单页面实现错误袋 | 多表单页面 |
| forms-05 | 表单提交后使用重定向模式 | PRG模式 |
| forms-06 | 正确处理文件上传 | 多部分表单 |
| forms-07 | 验证错误时保留表单状态 | 用户体验 |
| forms-08 | 为嵌套数据使用点记法 | 复杂表单 |
Navigation & Routing (HIGH)
导航与路由（高）
| ID | Rule | Context |
|---|---|---|
| nav-01 | Use Link component for internal navigation | SPA behavior |
| nav-02 | Use inertia_location for external redirects | External URLs |
| nav-03 | Implement preserve-scroll appropriately | Scroll position |
| nav-04 | Use preserve-state for component state | Form preservation |
| nav-05 | Configure proper HTTP methods on links | RESTful actions |
| nav-06 | Use the inertia route helper for static pages | Simple routes |
| nav-07 | Handle 303 redirects correctly | POST/PUT/PATCH/DELETE |
| ID | 规则 | 适用场景 |
|---|---|---|
| nav-01 | 使用Link组件进行内部导航 | SPA行为 |
| nav-02 | 使用inertia_location进行外部重定向 | 外部URL |
| nav-03 | 合理实现滚动位置保留 | 滚动位置 |
| nav-04 | 使用preserve-state保留组件状态 | 表单状态保留 |
| nav-05 | 为链接配置正确的HTTP方法 | RESTful操作 |
| nav-06 | 为静态页面使用inertia路由助手 | 简单路由 |
| nav-07 | 正确处理303重定向 | POST/PUT/PATCH/DELETE请求 |
Performance Optimization (MEDIUM-HIGH)
性能优化（中高）
| ID | Rule | Context |
|---|---|---|
| perf-01 | Implement code splitting with dynamic imports | Bundle size |
| perf-02 | Use prefetching for likely navigation | Perceived performance |
| perf-03 | Configure stale-while-revalidate caching | Data freshness |
| perf-04 | Use polling only when necessary | Real-time updates |
| perf-05 | Implement infinite scrolling with merge props | Large datasets |
| perf-06 | Optimize progress indicators | User feedback |
| perf-07 | Use async visits for non-blocking operations | Background tasks |
| ID | 规则 | 适用场景 |
|---|---|---|
| perf-01 | 结合动态导入实现代码分割 | 包体积优化 |
| perf-02 | 为可能的导航使用预加载 | 感知性能提升 |
| perf-03 | 配置stale-while-revalidate缓存 | 数据新鲜度 |
| perf-04 | 仅在必要时使用轮询 | 实时更新 |
| perf-05 | 结合合并Props实现无限滚动 | 大数据集 |
| perf-06 | 优化进度指示器 | 用户反馈 |
| perf-07 | 为非阻塞操作使用异步访问 | 后台任务 |
Security (MEDIUM-HIGH)
安全（中高）
| ID | Rule | Context |
|---|---|---|
| sec-01 | Implement authentication server-side | Auth patterns |
| sec-02 | Pass authorization results as props | Permission checks |
| sec-03 | Use history encryption for sensitive data | Browser history |
| sec-04 | Rely on Rails CSRF protection | Form security |
| sec-05 | Validate and sanitize all input server-side | Data validation |
| sec-06 | Use strong parameters in controllers | Mass assignment |
| ID | 规则 | 适用场景 |
|---|---|---|
| sec-01 | 在服务端实现认证 | 认证模式 |
| sec-02 | 将授权结果作为Props传递 | 权限校验 |
| sec-03 | 为敏感数据使用历史记录加密 | 浏览器历史 |
| sec-04 | 依赖Rails的CSRF保护 | 表单安全 |
| sec-05 | 在服务端验证并清洗所有输入 | 数据验证 |
| sec-06 | 在控制器中使用强参数 | 批量赋值防护 |
Testing (MEDIUM)
测试（中）
| ID | Rule | Context |
|---|---|---|
| test-01 | Use RSpec matchers for Inertia responses | RSpec testing |
| test-02 | Use Minitest assertions for Inertia | Minitest testing |
| test-03 | Test partial reloads and deferred props | Advanced features |
| test-04 | Implement end-to-end tests with Capybara | Integration testing |
| test-05 | Test flash messages after redirects | Flash testing |
| test-06 | Verify component rendering | Response validation |
| ID | 规则 | 适用场景 |
|---|---|---|
| test-01 | 使用RSpec匹配器测试Inertia响应 | RSpec测试 |
| test-02 | 使用Minitest断言测试Inertia | Minitest测试 |
| test-03 | 测试部分重载和延迟Props | 高级功能 |
| test-04 | 使用Capybara实现端到端测试 | 集成测试 |
| test-05 | 测试重定向后的flash消息 | 消息提示测试 |
| test-06 | 验证组件渲染 | 响应校验 |
Advanced Patterns (MEDIUM)
高级模式（中）
| ID | Rule | Context |
|---|---|---|
| adv-01 | Implement persistent layouts | State preservation |
| adv-02 | Use custom component path resolvers | Non-standard paths |
| adv-03 | Configure prop transformers | Data transformation |
| adv-04 | Handle SSR appropriately | SEO requirements |
| adv-05 | Implement view transitions | Modern animations |
| adv-06 | Use scroll regions for complex layouts | Scroll management |
| adv-07 | Handle events system effectively | Lifecycle hooks |
For detailed explanations, code examples, and implementation guidance for each rule, see AGENTS.md.
| ID | 规则 | 适用场景 |
|---|---|---|
| adv-01 | 实现持久化布局 | 状态保留 |
| adv-02 | 使用自定义组件路径解析器 | 非标准路径 |
| adv-03 | 配置Props转换器 | 数据转换 |
| adv-04 | 正确处理SSR | SEO需求 |
| adv-05 | 实现视图过渡 | 现代动画 |
| adv-06 | 为复杂布局使用滚动区域 | 滚动管理 |
| adv-07 | 高效处理事件系统 | 生命周期钩子 |
如需每条规则的详细说明、代码示例及实现指导，请查看AGENTS.md。