harper-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Harper Best Practices

Harper 最佳实践

Guidelines for building scalable, secure, and performant applications on Harper. These practices cover everything from initial schema design to advanced deployment strategies.

本指南介绍如何在Harper上构建可扩展、安全且高性能的应用，涵盖从初始模式设计到高级部署策略的所有内容。

When to Apply

适用场景

Reference these guidelines when:

Defining or modifying database schemas
Implementing or extending REST/WebSocket APIs
Handling authentication and session management
Working with custom resources and extensions
Optimizing data storage and retrieval (Blobs, Vector Indexing)
Deploying applications to Harper Fabric

在以下场景中可参考本指南：

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

Rule Categories by Priority

按优先级划分的规则类别

Priority	Category	Impact	Prefix
1	Schema & Data Design	HIGH	`schema-`
2	API & Communication	HIGH	`api-`
3	Logic & Extension	MEDIUM	`logic-`
4	Infrastructure & Ops	MEDIUM	`ops-`

优先级	类别	影响程度	前缀
1	模式与数据设计	高	`schema-`
2	API与通信	高	`api-`
3	逻辑与扩展	中	`logic-`
4	基础设施与运维	中	`ops-`

Quick Reference

快速参考

1. Schema & Data Design (HIGH)

1. 模式与数据设计（高优先级）

```
adding-tables-with-schemas
```
- Define tables using GraphQL schemas and directives
```
defining-relationships
```
- Link tables using the
```
@relationship
```
directive
```
vector-indexing
```
- Efficient similarity search with vector indexes
```
using-blob-datatype
```
- Store and retrieve large data (Blobs)
```
handling-binary-data
```
- Manage binary data like images or MP3s

```
adding-tables-with-schemas
```
- 使用GraphQL模式和指令定义表
```
defining-relationships
```
- 使用
```
@relationship
```
指令关联表
```
vector-indexing
```
- 借助向量索引实现高效相似性搜索
```
using-blob-datatype
```
- 存储和检索大型数据（Blobs）
```
handling-binary-data
```
- 管理图片或MP3等二进制数据

2. API & Communication (HIGH)

2. API与通信（高优先级）

```
automatic-apis
```
- Leverage automatically generated CRUD endpoints
```
querying-rest-apis
```
- Filters, sorting, and pagination in REST requests
```
real-time-apps
```
- WebSockets and Pub/Sub for live data updates
```
checking-authentication
```
- Secure apps with session-based identity verification

```
automatic-apis
```
- 利用自动生成的CRUD端点
```
querying-rest-apis
```
- REST请求中的过滤、排序和分页
```
real-time-apps
```
- 使用WebSocket和Pub/Sub实现实时数据更新
```
checking-authentication
```
- 基于会话的身份验证保障应用安全

3. Logic & Extension (MEDIUM)

3. 逻辑与扩展（中优先级）

```
custom-resources
```
- Define custom REST endpoints using JS/TS
```
extending-tables
```
- Add custom logic to generated table resources
```
programmatic-table-requests
```
- Advanced filtering and sorting in code
```
typescript-type-stripping
```
- Use TypeScript without build tools
```
caching
```
- Implement and define caching for performance

```
custom-resources
```
- 使用JS/TS定义自定义REST端点
```
extending-tables
```
- 为生成的表资源添加自定义逻辑
```
programmatic-table-requests
```
- 代码中的高级过滤与排序
```
typescript-type-stripping
```
- 无需构建工具即可使用TypeScript
```
caching
```
- 实现并定义缓存以提升性能

4. Infrastructure & Ops (MEDIUM)

4. 基础设施与运维（中优先级）

```
deploying-to-harper-fabric
```
- Scale globally with Harper Fabric
```
serving-web-content
```
- Ways to serve web content from Harper

```
deploying-to-harper-fabric
```
- 借助Harper Fabric实现全球扩展
```
serving-web-content
```
- 从Harper提供Web内容的方法

How to Use

使用方法

Read individual rule files for detailed explanations and code examples:

rules/adding-tables-with-schemas.md
rules/automatic-apis.md

阅读单个规则文件以获取详细说明和代码示例：

rules/adding-tables-with-schemas.md
rules/automatic-apis.md

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded:

AGENTS.md

如需查看包含所有扩展规则的完整指南，请参阅：

AGENTS.md