用途
该技能为特定项目提供资深级开发指导,在编写代码、实现功能、重构、审查代码架构或需要最佳实践时使用。它定义了项目的技术栈、架构模式、安全准则和代码质量标准,帮助开发者按照统一规范进行开发。
技术栈
项目使用以下技术:
- Next.js 15(App Router):服务端/客户端组件、API 路由、中间件
- MongoDB 搭配 Mongoose ODM:文档建模、索引、聚合
- NextAuth.js:基于凭证提供者和 JWT 会话的认证
- TypeScript(严格模式):强类型、泛型、工具类型
- Zustand:客户端状态管理
- Tailwind CSS:实用优先的样式方案
项目架构
API 路由(app/api/)
所有后端逻辑位于 Next.js API 路由中,示例包括使用 getServerSession 进行认证检查、connectDB 连接数据库,并返回统一格式的 JSON 响应。
Mongoose 模型(models/)
所有数据库模型使用 Mongoose schema 定义,包含 TypeScript 接口和 schema 字段配置,例如用户模型包含 name、email、password、roles 等字段,并启用时间戳。
认证(lib/auth.ts)
使用 NextAuth.js 的凭证提供者,在 API 路由中通过 getServerSession 获取会话,并检查用户权限。
权限系统(lib/permissions.ts)
基于角色的权限控制,定义 admin 和 user 等角色的权限列表,并在操作前检查会话中的权限。
安全最佳实践
- 密码处理:绝不存储明文密码,始终使用 bcrypt 进行哈希(saltRounds: 10),在保存前自动哈希,并提供密码比较方法。
- 环境变量:绝不将密钥提交到版本控制,始终使用环境变量(如 MONGODB_URI、NEXTAUTH_SECRET、NEXTAUTH_URL)。
- 输入验证:始终验证用户输入,可使用 Zod 或手动验证,示例包括创建文章时的字段校验。
翻译模式
博客实体使用内嵌翻译数组,包含 langCode、title、content、excerpt 等字段。查询时按语言代码查找翻译,并提供回退逻辑。
API 响应格式
统一响应格式包括成功响应(success、message、payload、id)、错误响应(fail、message、id、状态码)和分页响应(payload 包含数据、总数、页码、每页数量、总页数)。
Zustand 存储模式
使用 create 创建 store,定义状态和异步操作,通过请求工具获取数据并更新状态。
代码质量标准
- TypeScript:使用严格模式,避免 any,为所有数据形状定义接口,使用工具类型。
- 错误处理:使用 try/catch 捕获异常并返回适当错误响应。
- 异步/等待:使用 Promise.all 进行并行操作。
国际化支持
支持英语(en,LTR)和波斯语(fa,RTL),路由结构为 /[lang]/page,翻译文件位于 app/_utils/translation/,通过 HTML 的 dir 属性支持 RTL。
领域术语
- BlogPost:带翻译的博客文章
- BlogCategory:带翻译的文章分类
- BlogTag:带翻译的文章标签
- ProjectApplication:客户项目提交
- FreelancerApplication:自由职业者职位申请
适用场景
适用于该项目的前后端开发、代码审查、架构决策和安全实践参考。
限制
该技能针对特定项目(freelancelyst)的技术栈和架构,其他项目需调整。资料未提供安装命令、收费信息或具体使用步骤。