faasjs-best-practices

FaasJS 最佳实践

默认工作流

1. 确定任务领域，并加载负责该领域的最精简 FaasJS 技能。
2. 在选择导入项或路径之前，先阅读本地仓库说明和相关的 tsconfig.json 文件。
3. 将改动限制在任务范围内并尽量精简；避免无关重构、臆测性的回退方案，以及未同步修改配置的新别名。
4. 在边界处验证外部输入，在访问数据前检查身份验证、租户和权限范围，绝不记录机密信息。
5. 交接前，在可行时运行 vp check --fix && vp test；如不可行，记录原因并运行最小且有用的验证。

加载以下参考资料

• 新项目、功能布局、配置、CLI、注释、命名或共享测试：使用 faasjs-project-workflow。
• React UI、@faasjs/ant-design、useFaas、表单、表格、抽屉、CRUD 页面或 React 测试：使用 faasjs-react-ant-design。
• .api.ts、defineApi、HTTP 插件辅助函数、中间件、.job.ts 或 defineJob：使用 faasjs-api-jobs。
• @faasjs/pg、QueryBuilder、表声明、迁移或 PostgreSQL 测试：使用 faasjs-pg。
• 在同一事务中将任务加入队列的业务写入：同时加载 faasjs-pg 和 faasjs-api-jobs。
• 插件生命周期、注入字段、日志记录器用法、Node 引导流程或运行时配置加载：使用 faasjs-plugins-runtime。
• @faasjs/utils、JSON、YAML、流辅助函数或验证辅助函数：使用 faasjs-utils-data。
• faas.yaml、路由、HTTP 协议或插件契约的规范性运行时行为：使用 faasjs-specs。

注意事项

• Zod 用于外部输入契约；将内部的 typeof、instanceof 和 null 检查保留为控制流谓词。
• 本地 TypeScript 导入不带扩展名，并优先使用已配置的别名，而不是深层相对导入。
• 对 React Hook 的返回值和顶层 defineApi/defineJob 处理器上下文进行解构；让业务值以 params.key 的形式清晰可见。
• 直接返回值，除非中间变量用于说明非简单条件、会被复用，或能提升可读性。
• 生成的任务路径应与运行时发现机制保持一致，并且不要让事务作用域内的客户端逸出回调。

验证

• 使用 vp check --fix 进行格式化和 lint。
• 使用 vp test 或 vp test <pattern> 运行测试。
• 添加、重命名、移动或移除 .api.ts 或 .job.ts 文件后，运行 npx faas types。
• 仅在数据库变更确有需要且 DATABASE_URL 可用时，运行 npx faasjs-pg migrate 或有针对性的 PG 检查。