快速开始

这一页的目标不是只返回一个 Hello World，而是让你在几分钟内得到一个适合继续扩展的项目骨架。

这一页会带你学会什么

在这一页里，你会：

• 跑起一个可工作的服务
• 建立一个适合扩展的小型目录结构
• 接上一层基础 middleware
• 把 validation 和契约输出接起来

安装

pnpm add orvajs
pnpm add -D typescript tsx

已发布的 orvajs npm 包只包含 dist、README.md 和 LICENSE。如果你要本地运行文档站，需要先获取完整仓库：

git clone https://github.com/jieceng/orva.git
cd orva
pnpm install
pnpm docs:dev

第一个服务

import { createOrva } from 'orvajs';
import { serveNode } from 'orvajs/adapters/node';

const app = createOrva();

app.get('/', (c) => c.text('orva is running'));
app.get('/users/:id', (c) => c.json({
  id: c.params.id,
  q: c.query.q ?? null,
}));

serveNode(app, { port: 3000 });

启动后访问：

• GET http://localhost:3000/
• GET http://localhost:3000/users/42?q=active

推荐目录结构

src/
  app.ts
  routes/
    users.ts
  middlewares/
    auth.ts
  contracts/
    user.ts
server.ts

src/app.ts:

import { createOrva } from 'orvajs';
import { cors, secureHeaders } from 'orvajs/middlewares';
import { usersApp } from './routes/users';

export const app = createOrva()
  .use(cors(), secureHeaders())
  .route('/api', usersApp);

src/routes/users.ts:

import { createOrva } from 'orvajs';

export const usersApp = createOrva()
  .get('/', (c) => c.json([{ id: 'u_1', name: 'Ada' }]))
  .get('/:id', (c) => c.json({ id: c.params.id, name: 'Ada' }));

server.ts:

import { serveNode } from 'orvajs/adapters/node';
import { app } from './src/app';

serveNode(app, { port: 3000 });

先接上最基本的生产默认栈

大多数项目起步时，建议至少先加这些：

import { createOrva } from 'orvajs';
import {
  bodyLimit,
  cors,
  requestId,
  responseTime,
  secureHeaders,
} from 'orvajs/middlewares';

export const app = createOrva().use(
  requestId(),
  cors(),
  secureHeaders(),
  bodyLimit({ maxBytes: 1024 * 1024 }),
  responseTime(),
);

接入 validator

import { z } from 'zod';
import { createOrva } from 'orvajs';
import { zodValidator } from 'orvajs/validator/zod';

const createUserSchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});

export const app = createOrva().post(
  '/users',
  zodValidator('json', createUserSchema),
  (c) => c.json(c.valid('json'), 201),
);

接入 OpenAPI 和 RPC

服务端应用保持不变，只是在旁边增加契约出口：

import { createRPCMetadata } from 'orvajs/rpc';
import { createOpenAPIDocument } from 'orvajs/openapi';
import { app } from './app';

export const rpcMetadata = createRPCMetadata(app);

export const openapi = createOpenAPIDocument(app, {
  info: {
    title: 'Orva Example',
    version: '1.0.0',
  },
});

导入策略建议

应用项目

import { cors, requestId } from 'orvajs/middlewares';

对外发布包、模板、基建层

import { cors } from 'orvajs/middlewares/cors';
import { requestId } from 'orvajs/middlewares/request-id';

Import Strategy Demo

在应用内快速比较聚合导入和细粒度子模块导入。

import { cors } from 'orvajs/middlewares/cors';
import { requestId } from 'orvajs/middlewares/request-id';
import { secureHeaders } from 'orvajs/middlewares/secure-headers';

下一步

• 看 路由与组合
• 看 Context 与响应
• 看 类型链路
• 看 中间件与类型累积
• 看 测试与质量