核心解法是让文档生成与代码变更自动绑定：用IDE Helper自动生成模型PHPDoc、Request Docs实时提取API文档、laravelcollective-html统一表单语义，形成数据库→模型→表单→文档的连贯链路。
核心解法是让文档生成过程与代码变更自动绑定，而不是依赖人工同步。重点不在“写得更勤”，而在于“不用手写”。
用 Laravel IDE Helper 自动生成模型字段注释
数据库字段变动后，IDE 无法感知，导致属性提示失效、类型错误难发现。手动补 @property 注释极易遗漏或写错类型。
- 安装后运行
php artisan ide-helper:models，工具会扫描迁移文件和表结构，直接在模型顶部插入完整 PHPDoc - 支持自定义类型映射，比如把数据库的
json字段自动转为@property array $settings - 可配置排除特定模型（如
User），避免为第三方扩展模型生成冗余注释
用 Laravel Request Docs 实现 API 文档随接口实时更新
控制器方法改了参数、验证规则变了、返回结构加了字段——只要没手动更新文档，前端就只能猜。
- 它能自动提取
FormRequest的rules()方法、控制器中注入的 Request 类、甚至@LRDparam标记的注释 - 按 URI 模式自动分组，例如
^api/v1/下所有路由归入“V1 接口”模块，结构清晰不混乱 - 生产环境默认禁用，通过中间件控制访问权限，避免文档泄露
用 rdx/laravelcollective-html 统一视图层语义，间接提升文档可读性
HTML 表单代码散落在 Blade 文件里，没有统一结构，新人看不懂字段含义，也难以提取成接口文档。
- 用
Form::text('email')替代原生<input name="email">，字段名、类型、是否必填等信息天然集中 - 该包完全兼容旧项目中的
laravelcollective/html调用，零代码修改即可切换 - 配合 IDE Helper，表单字段也能被识别为模型属性，形成从数据库 → 模型 → 表单 → 文档的连贯链路
不复杂但容易忽略：这些工具不是堆砌功能，而是把文档生成嵌进开发动线里——写完迁移就跑一次 models 命令，提交控制器前确认 request-docs 能正确解析，表单一律走 Form 构建器。文档自然就跟上了。
