Norish开发入门：从API接口到插件开发的完整技术文档

Norish开发入门：从API接口到插件开发的完整技术文档

【免费下载链接】norishNorish - A realtime, self-hosted recipe app for families & friends项目地址: https://gitcode.com/gh_mirrors/no/norish

Norish是一款实时的、自托管的家庭和朋友食谱应用，本指南将帮助开发者从API接口使用到插件开发，快速掌握Norish的技术架构和扩展方式。通过本文，你将了解如何搭建开发环境、利用API接口进行数据交互，以及开发自定义插件来扩展Norish的功能。

开发环境搭建

环境要求

• Node.js22.22.0（见.nvmrc）
• pnpm10.x或更高版本
• Docker（用于PostgreSQL、Redis和无头Chrome）
• Git

本地开发设置

# 克隆仓库 git clone https://gitcode.com/gh_mirrors/no/norish cd norish # 安装依赖 pnpm install # 创建环境文件 cp .env.example .env.local # 启动所需服务（Postgres、Redis、Chrome） pnpm run docker:up # 运行Web应用 pnpm run dev # 运行移动应用（Expo） pnpm run dev:mobile

至少需要在.env.local中配置DATABASE_URL、REDIS_URL、AUTH_URL和MASTER_KEY（使用openssl rand -base64 32生成）。详细配置可参考Server & runtime和Database。

API接口详解

Norish在/api/v1路径下提供HTTP API接口，方便开发者进行数据交互和扩展。

认证方式

通过以下任一方式传递API密钥：

x-api-key: <your-api-key>

Authorization: Bearer <your-api-key>

注意：/api/docs和/api/openapi.json需要已登录的Web会话；GET /api/v1/health是公开的健康检查接口；其他所有/api/v1端点都需要API凭证。

主要端点

健康检查

• GET /api/v1/health- 公共健康检查接口，返回API和内部解析器服务的健康状态。

食谱管理

• GET /api/v1/recipes/{id}- 获取指定ID的食谱详情
• POST /api/v1/recipes/search- 列出食谱，支持可选过滤条件
• POST /api/v1/recipes/import/url- 从URL导入食谱
• POST /api/v1/recipes/import/paste- 粘贴导入食谱

POST /api/v1/recipes/search返回分页的食谱列表，可选过滤条件包括search、searchFields、tags、categories、filterMode、sortMode、minRating和maxCookingTime。cursor默认为0，limit默认为50。

食材管理

• GET /api/v1/groceries- 获取食材列表
• POST /api/v1/groceries- 添加新食材
• PATCH /api/v1/groceries/{id}/done- 标记食材为已购买
• PATCH /api/v1/groceries/{id}/undone- 标记食材为未购买
• PATCH /api/v1/groceries/{id}/store- 更新食材的存储位置
• DELETE /api/v1/groceries/{id}- 删除食材

针对单个食材的修改端点需要version字段以实现乐观并发控制。PATCH /api/v1/groceries/{id}/store在请求体中接受storeId和可选的savePreference。

商店管理

• GET /api/v1/stores- 获取商店列表
• POST /api/v1/stores- 添加新商店

计划食谱

• GET /api/v1/planned-recipes/today- 获取今日计划食谱
• GET /api/v1/planned-recipes/week- 获取本周计划食谱
• GET /api/v1/planned-recipes/month- 获取本月计划食谱
• POST /api/v1/planned-recipes- 添加计划食谱
• DELETE /api/v1/planned-recipes/{itemId}- 删除计划食谱

计划食谱范围端点使用服务器时区来确定今天/周/月的边界，周范围是从周一到周日。

插件开发指南

虽然Norish目前没有专门的插件系统，但可以通过以下方式扩展功能：

共享模块开发

Norish采用模块化架构，通过创建共享模块可以实现功能扩展。主要共享模块位于packages/shared-react/src/hooks/和packages/shared-react/src/contexts/目录下。

例如，创建一个新的共享钩子模块：

1. 在packages/shared-react/src/hooks/目录下创建新的钩子文件
2. 实现钩子逻辑，确保不导入特定平台的模块
3. 在packages/shared-react/src/index.ts中导出新钩子

集成第三方服务

可以通过API接口集成第三方服务，例如：

• 集成AI食材识别服务
• 添加新的食谱导入来源
• 连接外部日历服务

集成方式通常是创建新的API端点或使用现有端点的扩展参数，具体实现可参考packages/api/src/parser/目录下的解析器模块。

自定义主题和样式

Norish使用Tailwind CSS进行样式管理，可以通过以下方式自定义主题：

1. 修改tooling/tailwind/heroui-theme.css文件
2. 扩展tooling/tailwind/heroui-theme.js中的主题配置
3. 在应用中使用自定义CSS类

高级开发技巧

测试策略

Norish使用Vitest进行测试，测试文件通常与被测试模块放在同一目录下，命名为*.test.ts或*.test.tsx。可以使用以下命令运行测试：

pnpm run test

代码质量工具

项目使用ESLint和Prettier进行代码质量控制，相关配置位于tooling/eslint/和tooling/prettier/目录下。提交代码前建议运行：

pnpm run lint pnpm run format

性能优化

• 使用React.memo和useMemo优化组件渲染
• 合理使用TanStack Query进行数据缓存
• 优化图片加载，使用适当的尺寸和格式

总结

Norish提供了强大的API接口和模块化架构，使开发者能够轻松扩展其功能。通过本文介绍的开发环境搭建、API接口使用和插件开发方法，你可以开始构建自定义功能和集成第三方服务。如需更多帮助，请参考项目中的开发命令文档和贡献指南。

祝你的Norish开发之旅顺利！ 🚀

【免费下载链接】norishNorish - A realtime, self-hosted recipe app for families & friends项目地址: https://gitcode.com/gh_mirrors/no/norish