Agent X-Ray

Notes Skills About

Skills/

正在取…

INSTALL

FILES

本页目录

苏ICP备2025204887号-2

Skills/开发框架/encore-service

encore-service精选

拆服务与定目录结构:单体还是多服务、服务边界、encore.service.ts

1 个文件 · 5.5 KB · 更新于 2026-09-03 · 出处 encoredev/skills ↗

GitHub ↗下载 zip · 2 KB

INSTALL

npx skills add encoredev/skills --skill encore-service

copy

装进 .claude/skills/encore-service/;Codex 读 .agents/skills/,同一目录结构。

FILES

▾encore-service/

SKILL.md5.5 KB

本页目录

Instructions Application Patterns Service-to-Service Calls When to Split Services Service with Middleware Guidelines

SKILL.mdmarkdown · 5.5 KB · 207 行

copy

nameencore-servicedescriptionPlan how to split an Encore.ts application into services and lay out its directory structure. Architecture and decomposition, not first-time CLI install (that's `encore-getting-started`).when_to_useUser is deciding monolith vs. microservices, weighing "one service or several", drawing service boundaries, planning a multi-service system (e.g. orders + payments + inventory + shipping), creating an `encore.service.ts`, naming directories/folders, designing systems-of-services hierarchies, or asking for an application architecture / project layout recommendation. Trigger phrases: "lay out the directories", "directory structure", "service boundaries", "one service or several", "monolith vs microservices", "where to put", "systems of services".

Encore Service Structure

Instructions

Creating a Service

Every Encore service needs an encore.service.ts file:

typescript

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

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

Minimal Service Structure

text

my-service/
├── encore.service.ts    # Service definition (required)
├── api.ts               # API endpoints
└── db.ts                # Database (if needed)

Application Patterns

Single Service (Recommended Start)

Best for new projects - start simple, split later if needed:

text

my-app/
├── package.json
├── encore.app
├── encore.service.ts
├── api.ts
├── db.ts
└── migrations/
    └── 001_initial.up.sql

For distributed systems with clear domain boundaries:

text

my-app/
├── encore.app
├── package.json
├── user/
│   ├── encore.service.ts
│   ├── api.ts
│   └── db.ts
├── order/
│   ├── encore.service.ts
│   ├── api.ts
│   └── db.ts
└── notification/
    ├── encore.service.ts
    └── api.ts

Large Application (System-based)

Group related services into systems:

text

my-app/
├── encore.app
├── commerce/
│   ├── order/
│   │   └── encore.service.ts
│   ├── cart/
│   │   └── encore.service.ts
│   └── payment/
│       └── encore.service.ts
├── identity/
│   ├── user/
│   │   └── encore.service.ts
│   └── auth/
│       └── encore.service.ts
└── comms/
    ├── email/
    │   └── encore.service.ts
    └── push/
        └── encore.service.ts

Service-to-Service Calls

Import other services from ~encore/clients:

typescript

import { user } from "~encore/clients";

export const getOrderWithUser = api(
  { method: "GET", path: "/orders/:id", expose: true },
  async ({ id }): Promise<OrderWithUser> => {
    const order = await getOrder(id);
    const orderUser = await user.get({ id: order.userId });
    return { ...order, user: orderUser };
  }
);

When to Split Services

Split when you have:

Signal	Action
Different scaling needs	Split (e.g., auth vs analytics)
Different deployment cycles	Split
Clear domain boundaries	Split
Shared database tables	Keep together
Tightly coupled logic	Keep together
Just organizing code	Use folders, not services

Service with Middleware

typescript

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

const loggingMiddleware = middleware(
  { target: { all: true } },
  async (req, next) => {
    console.log(`Request: ${req.requestMeta?.path}`);
    return next(req);
  }
);

export default new Service("my-service", {
  middlewares: [loggingMiddleware],
});

Middleware Targeting

Control which endpoints middleware applies to:

typescript

// Apply to all endpoints
middleware({ target: { all: true } }, handler);

// Apply only to authenticated endpoints
middleware({ target: { auth: true } }, handler);

// Apply only to exposed (public) endpoints
middleware({ target: { expose: true } }, handler);

// Apply to raw endpoints only
middleware({ target: { isRaw: true } }, handler);

// Apply to streaming endpoints only
middleware({ target: { isStream: true } }, handler);

// Apply to endpoints with specific tags
middleware({ target: { tags: ["admin", "internal"] } }, handler);

Middleware Request Object

The request object provides access to:

typescript

const myMiddleware = middleware(
  { target: { all: true } },
  async (req, next) => {
    // For typed and streaming APIs
    const meta = req.requestMeta;  // { method, path, pathParams }

    // For raw endpoints
    const rawReq = req.rawRequest;
    const rawRes = req.rawResponse;

    // For streaming endpoints
    const stream = req.stream;

    // Custom data to pass to handlers
    req.data = { startTime: Date.now() };

    const resp = await next(req);

    // Modify response headers
    resp.header.set("X-Response-Time", `${Date.now() - req.data.startTime}ms`);

    return resp;
  }
);

Services cannot be nested within other services
Start with one service, split when there's a clear reason
Use ~encore/clients for cross-service calls (never direct imports)
Each service can have its own database
Service names should be lowercase, descriptive
Don't create services just for code organization - use folders instead

Encore Service Structure

Instructions

Creating a Service

Minimal Service Structure

Application Patterns

Single Service (Recommended Start)

Multi-Service

Large Application (System-based)

Service-to-Service Calls

When to Split Services

Service with Middleware

Middleware Targeting

Middleware Request Object

Guidelines