异常处理与代码质量

异常处理

两种口径，别混：

• 业务失败（参数错、数据不存在、无权限）→ 用 warning('...') 返回 {code:400, msg}，不抛异常。
• 系统级异常 / 扩展契约违反（配置非法、接管类未实现契约、地址不合规）→ throw new \app\exception\ApiException($msg)。例如 ServiceRegistry::provide() 对未覆写 KEY 的 Provider 直接抛 ApiException；地址校验 assertPublicUrl()/normalizeDownloadUrl() 也抛 ApiException。

常见错误文案：

场景	文案
参数缺失	参数错误
记录不存在	{模块名}不存在
写失败	{操作}失败
关联占用	存在{关联数据}，无法删除
内置数据	内置{模块名}不能删除

事务用 $this->transaction(function () { ... }) 包裹，闭包内抛异常自动回滚，不要手写 try/commit/rollback 漏掉回滚。

"尽力而为"型 API（队列 dispatch、推送 toChannel、任务注册）在依赖不可用时返回 false 并记日志，不抛异常——调用方按返回值降级，别当必然成功。

命名

	后端	前端
类/组件	大驼峰 UserController	大驼峰 UserDialog
方法/变量	小驼峰 getUserList / $userInfo	小驼峰 userInfo
常量	全大写 MAX_SIZE	全大写 MAX_COUNT

插件标识另有硬约束（am_ 前缀 + 后缀 ≥5 字符 + 非保留名 + 全局唯一），见提交前自检清单。

注释

关键类/方法写 PHPDoc/JSDoc，说明用途、参数、返回。逻辑复杂的段落加行内注释解释"为什么"，不解释"做了什么"。

代码风格

• 缩进：PHP 4 空格，TS/Vue 2 空格。
• 引号：单引号为主，JSON 双引号。
• 必加行尾分号；行宽 ≤120；方法间空一行。
• 前端由 ESLint + Prettier + Stylelint 把关，后端提交前 php -l/静态检查；husky pre-commit 会拦截未通过项。

安全

• SQL 注入：只用 ORM，不拼字符串 SQL。
• XSS：v-html 慎用，渲染外部内容前过滤。
• 密码：只用 passwordHash()/passwordVerify()（内部 password_hash/password_verify），不自定义哈希。
• 文件上传：校验类型与大小，落位与访问走存储体系。
• 越权：功能权限 + 行级数据权限双重校验，前端 v-auth 只是体验层。
• 远程地址：加载插件图标/远程资源前用 assertPublicUrl() 挡内网地址、只放行 http/https。

性能

• 数据库：with() 预加载防 N+1、field() 只取所需列、合理使用索引。
• 缓存：读多写少走缓存、删除策略更新（见缓存规范）。
• 前端：列表分页、搜索防抖 500ms、图片懒加载、组件按需加载。

提交

Conventional Commits，type 限 feat/fix/docs/style/refactor/perf/test/build/ci/revert/chore/wip；type(scope): subject。详见贡献与许可。