encore-getting-started

开始使用 Encore.ts

说明

安装 Encore CLI

# macOS
brew install encoredev/tap/encore

# Linux/WSL
curl -L https://encore.dev/install.sh | bash

# Windows (PowerShell)
iwr https://encore.dev/install.ps1 | iex

创建新应用

# Interactive - choose from templates
encore app create my-app

# Or start with a blank app
encore app create my-app --example=ts/hello-world

项目结构

一个最简 Encore.ts 应用：

my-app/
├── encore.app           # App configuration
├── package.json         # Dependencies
├── tsconfig.json        # TypeScript config
├── encore.service.ts    # Service definition
└── api.ts               # API endpoints

encore.app 文件

// encore.app
{
    "id": "my-app"
}

此文件标记 Encore 应用的根目录。id 是应用的唯一标识符。

定义服务

创建 encore.service.ts 来定义服务：

// encore.service.ts
import { Service } from "encore.dev/service";

export default new Service("my-service");

创建第一个 API

// api.ts
import { api } from "encore.dev/api";

interface HelloResponse {
  message: string;
}

export const hello = api(
  { method: "GET", path: "/hello", expose: true },
  async (): Promise<HelloResponse> => {
    return { message: "Hello, World!" };
  }
);

运行应用

# Start the development server
encore run

# Your API is now available at http://localhost:4000

打开本地仪表板

# Opens the local development dashboard
encore run
# Then visit http://localhost:9400

仪表板会显示：

• 所有服务和端点
• 请求/响应日志
• 数据库查询
• 跟踪和跨度

常用 CLI 命令

命令	说明
encore run	启动本地开发服务
encore test	运行测试
encore db shell <db>	打开数据库的 psql shell
encore gen client	生成 API 客户端代码
encore app link	关联现有的 Encore Cloud 应用

添加数据库

// db.ts
import { SQLDatabase } from "encore.dev/storage/sqldb";

const db = new SQLDatabase("mydb", {
  migrations: "./migrations",
});

创建迁移：

-- migrations/1_create_table.up.sql
CREATE TABLE items (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL
);

后续步骤

• 添加更多端点（参见 encore-api 技能）
• 添加身份验证（参见 encore-auth 技能）
• 添加 Pub/Sub 主题（encore-pubsub）、定时任务（encore-cron）、存储桶（encore-bucket）、密钥（encore-secret）或缓存（encore-cache）
• 部署到 Encore Cloud：先运行 encore app link，然后运行 git push encore