mcpField
H
harper-best-practices

harper-best-practices

github.com/harperfast开发3754 次安装今天更新
代码仓库

关于 harper-best-practices

面向 Harper 应用开发者的实践指南，按优先级整理数据库模式、API、扩展逻辑和运维部署规则，并链接到详细规则文件。

主要功能

  1. 01按优先级组织规则
  2. 02涵盖 GraphQL 模式设计
  3. 03指导 REST 与 WebSocket API
  4. 04介绍认证、缓存和自定义资源
  5. 05包含部署与运维建议

适用场景

  1. 01设计或修改 Harper 数据库模式
  2. 02实现 REST 或 WebSocket API
  3. 03扩展 Harper 资源和表逻辑
  4. 04部署应用到 Harper Fabric

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/harperfast/skills --skill harper-best-practices

安装后在 Claude Code 中输入/harper-best-practices确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

AGENTS.md
rules.manifest.yaml
rules/
adding-tables-with-schemas.md
automatic-apis.md
caching.md
checking-authentication.md
creating-a-fabric-account-and-cluster.md
creating-harper-apps.md
custom-resources.md
defining-relationships.md
delegating-to-the-built-in-agent.md
deploying-from-ci.md
deploying-to-harper-fabric.md
extending-tables.md
handling-binary-data.md
load-env.md
logging.md
programmatic-table-requests.md
querying-rest-apis.md
real-time-apps.md
schema-design-tooling.md
serving-web-content.md
typescript-type-stripping.md
using-blob-datatype.md
v5-upgrade.md
vector-indexing.md

详细介绍

Harper 最佳实践

在 Harper 上构建可扩展、安全且高性能应用的指南。这些实践涵盖从初始模式设计到高级部署策略的方方面面。

适用场景

在以下情况下，请参考这些指南：

  • 定义或修改数据库模式
  • 实现或扩展 REST/WebSocket API
  • 处理身份验证和会话管理
  • 使用自定义资源和扩展
  • 优化数据存储和检索（Blob、向量索引）
  • 将应用部署到 Harper Fabric

工作原理

  1. 查看任务需求（模式设计、API 需求或基础设施设置）。
  2. 查阅“按优先级划分的规则类别”下的相关类别，了解决策的影响。
  3. 参阅下方“快速参考”部分中的详细规则文件，并应用具体规则。
  4. 如果要构建新表，优先遵循 schema- 规则。
  5. 如果要扩展功能，请查阅 logic- 和 api- 规则。
  6. 部署前，根据 ops- 规则验证实现。

示例

请参阅下方各规则子章节中的具体示例（GraphQL 模式、REST 查询模式和部署工作流片段）。

按优先级划分的规则类别

优先级类别影响前缀
1模式与数据设计HIGHschema-
2API 与通信HIGHapi-
3逻辑与扩展MEDIUMlogic-
4基础设施与运维MEDIUMops-

快速参考

1. 模式与数据设计（HIGH）
  • adding-tables-with-schemas — 使用 GraphQL 模式向 Harper 数据库添加表的指南。
  • schema-design-tooling — Harper 模式设计最佳实践，包括核心指令和 GraphQL 工具配置。
  • defining-relationships — 如何使用 GraphQL 在 Harper 中定义和使用表之间的关系。
  • vector-indexing — 如何在 Harper 中启用和查询向量索引，以进行相似性搜索。
  • using-blob-datatype — 如何使用 Blob 数据类型在 Harper 中高效存储二进制数据。
  • handling-binary-data — 如何在 Harper 中存储和提供图像或音频等二进制数据。
2. API 与通信（HIGH）
  • automatic-apis — 如何使用 Harper 自动生成的 REST 和 WebSocket API。
  • querying-rest-apis — 如何使用查询参数筛选、排序和分页 Harper REST API。
  • real-time-apps — 如何在 Harper 中使用 WebSocket 和 Pub/Sub 构建实时功能。
  • checking-authentication — 如何在 Harper 资源中处理用户身份验证和会话。
3. 逻辑与扩展（MEDIUM）
  • custom-resources — 如何在 Harper 中使用 JavaScript 或 TypeScript 定义自定义 REST 端点。
  • extending-tables — 如何向 Harper 中自动生成的表资源添加自定义逻辑。
  • programmatic-table-requests — 如何使用 tables 对象以编程方式与 Harper 表交互。
  • typescript-type-stripping — 如何在 Harper 中直接运行 TypeScript 文件，无需构建步骤。
  • caching — 如何在 Harper 中实现来自外部来源的集成数据缓存。
4. 基础设施与运维（中）
  • deploying-to-harper-fabric — 如何通过 CLI 将 Harper 应用部署到 Harper Fabric、检查发布是否已通过认证，以及通过激活先前发布的 deployment_id 回滚。
  • deploying-from-ci — 如何通过 GitHub Actions 使用 OIDC 可信发布来部署 Harper 应用，让 CI 无需存储 Harper 凭据；其中包括使用 harper deploy setup=true provider=github-actions 进行单命令设置。
  • creating-a-fabric-account-and-cluster — 如何创建 Harper Fabric 账户、组织和集群。
  • creating-harper-apps — 如何使用 CLI 初始化新的 Harper 应用。
  • serving-web-content — 如何在 Harper 中提供静态文件和集成的 Vite/React 应用。
  • logging — Harper 日志记录的最佳实践，包括控制台捕获、细粒度的日志记录器接口和以编程方式检索日志。
  • load-env — 如何使用 loadEnv 插件将 .env 文件中的环境变量加载到 Harper 应用中。
  • v5-upgrade — 将 Harper 应用迁移到 v5 时的破坏性变更和建议的更新。
  • delegating-to-the-built-in-agent — 如何通过 CLI 和 Agent 操作 API 将任务委派给 Harper 的内置 Agent。

使用方法

阅读各个规则文件，了解详细说明和代码示例：

rules/adding-tables-with-schemas.md
rules/schema-design-tooling.md
rules/automatic-apis.md
rules/creating-harper-apps.md
rules/logging.md

完整编译文档

如需查看包含所有展开规则的完整指南：AGENTS.md

评论

支持 Markdown