CRUD API

一个完整的 RESTful CRUD API 示例，展示 VextJS 的服务层、中间件、参数校验、错误处理等核心能力。

项目结构

crud-api/
  ├── src/
  │   ├── config/
  │   │   └── default.ts
  │   ├── middlewares/
  │   │   └── auth.ts
  │   ├── routes/
  │   │   ├── index.ts
  │   │   └── users.ts
  │   ├── services/
  │   │   └── user.ts
  │   └── index.ts
  ├── test/
  │   └── users.test.ts
  ├── package.json
  └── tsconfig.json

1. 初始化项目

npx vextjs create crud-api
cd crud-api
pnpm install

2. 配置

// src/config/default.ts
export default {
  port: 3000,
  adapter: "native",
  logger: {
    level: "debug",
    pretty: true,
  },
  cors: {
    enabled: true,
    origins: ["*"],
  },
  rateLimit: {
    enabled: true,
    max: 100,
    window: 60,
  },
  response: {
    wrap: true,
    hideInternalErrors: false, // 开发环境显示错误详情
  },
  openapi: {
    enabled: true,
    title: "CRUD API 示例",
    version: "1.0.0",
    description: "一个完整的用户管理 RESTful API",
    tags: [
      { name: "基础", description: "基础接口" },
      { name: "用户", description: "用户管理接口" },
    ],
    securitySchemes: {
      bearerAuth: {
        type: "http",
        scheme: "bearer",
        bearerFormat: "JWT",
        description: "使用 Bearer Token 认证",
      },
    },
    guardSecurityMap: {
      auth: "bearerAuth",
    },
  },
  // 路由级中间件白名单
  middlewares: [{ name: "auth" }],
};

Tip

config.openapi.guardSecurityMap 将路由中间件名称 'auth' 映射到 OpenAPI 安全方案 bearerAuth。当路由声明 middlewares: ['auth'] 时，OpenAPI 文档会自动标记该接口需要 Bearer Token 认证。

3. 认证中间件

// src/middlewares/auth.ts
import { defineMiddleware } from "vextjs";

/**
 * 简易认证中间件
 *
 * 生产环境中应使用 JWT 库（如 jose）进行令牌验证。
 * 此处为了演示简化为静态 token 校验。
 */
export default defineMiddleware(async (req, _res, next) => {
  const authorization = req.headers.authorization;

  if (!authorization) {
    req.app.throw(401, "未提供认证令牌");
  }

  const token = authorization.replace("Bearer ", "");

  if (!token || token === "undefined") {
    req.app.throw(401, "认证令牌格式无效");
  }

  // 模拟 JWT 解码（生产环境应使用 jose/jsonwebtoken 等库）
  try {
    // 简单示例：token 格式为 "user-{id}-{role}"
    const parts = token.split("-");
    if (parts.length < 3 || parts[0] !== "user") {
      req.app.throw(401, "认证令牌无效");
    }

    req.user = {
      id: parts[1],
      role: parts[2],
    };
  } catch {
    req.app.throw(401, "认证令牌解析失败");
  }

  await next();
});

为 req.user 添加类型声明：

// types/vext.d.ts
declare module "vextjs" {
  interface VextRequest {
    user?: {
      id: string;
      role: string;
    };
  }
}

4. 服务层

// src/services/user.ts
import type { VextApp, VextLogger } from "vextjs";

/**
 * 用户数据接口
 */
interface User {
  id: string;
  name: string;
  email: string;
  age?: number;
  role: string;
  createdAt: string;
  updatedAt: string;
}

/**
 * 用户服务
 *
 * 使用内存存储演示 CRUD 操作。
 * 生产环境中应替换为数据库操作（如 Drizzle ORM / Prisma）。
 */
export default class UserService {
  private logger: VextLogger;
  private users: Map<string, User> = new Map();
  private nextId = 1;

  constructor(private app: VextApp) {
    this.logger = app.logger.child({ service: "UserService" });

    // 初始化一些测试数据
    this.seed();
  }

  /**
   * 填充初始测试数据
   */
  private seed(): void {
    const seedUsers = [
      { name: "Alice", email: "alice@example.com", age: 28, role: "admin" },
      { name: "Bob", email: "bob@example.com", age: 32, role: "user" },
      { name: "Charlie", email: "charlie@example.com", role: "user" },
    ];

    for (const u of seedUsers) {
      const id = String(this.nextId++);
      const now = new Date().toISOString();
      this.users.set(id, { id, ...u, createdAt: now, updatedAt: now });
    }

    this.logger.info({ count: this.users.size }, "初始数据已加载");
  }

  /**
   * 分页查询用户列表
   */
  async findAll(options: {
    page: number;
    limit: number;
    keyword?: string;
  }): Promise<{
    items: User[];
    total: number;
    page: number;
    limit: number;
    totalPages: number;
  }> {
    this.logger.debug(options, "查询用户列表");

    let allUsers = Array.from(this.users.values());

    // 关键词搜索（按 name 或 email 模糊匹配）
    if (options.keyword) {
      const kw = options.keyword.toLowerCase();
      allUsers = allUsers.filter(
        (u) =>
          u.name.toLowerCase().includes(kw) ||
          u.email.toLowerCase().includes(kw),
      );
    }

    const total = allUsers.length;
    const totalPages = Math.ceil(total / options.limit);
    const start = (options.page - 1) * options.limit;
    const items = allUsers.slice(start, start + options.limit);

    return {
      items,
      total,
      page: options.page,
      limit: options.limit,
      totalPages,
    };
  }

  /**
   * 根据 ID 查询用户
   */
  async findById(id: string): Promise<User | null> {
    this.logger.debug({ userId: id }, "查询用户");
    return this.users.get(id) ?? null;
  }

  /**
   * 创建用户
   */
  async create(data: {
    name: string;
    email: string;
    age?: number;
    role?: string;
  }): Promise<User> {
    this.logger.info({ email: data.email }, "创建用户");

    // 检查邮箱唯一性
    for (const user of this.users.values()) {
      if (user.email === data.email) {
        this.app.throw(409, "邮箱已注册", 10001);
      }
    }

    const id = String(this.nextId++);
    const now = new Date().toISOString();

    const user: User = {
      id,
      name: data.name,
      email: data.email,
      age: data.age,
      role: data.role ?? "user",
      createdAt: now,
      updatedAt: now,
    };

    this.users.set(id, user);
    this.logger.info({ userId: id, email: data.email }, "用户创建成功");

    return user;
  }

  /**
   * 更新用户
   */
  async update(
    id: string,
    data: { name?: string; email?: string; age?: number },
  ): Promise<User> {
    this.logger.info({ userId: id }, "更新用户");

    const user = this.users.get(id);
    if (!user) {
      this.app.throw(404, "用户不存在");
    }

    // 如果更新邮箱，检查唯一性
    if (data.email && data.email !== user.email) {
      for (const u of this.users.values()) {
        if (u.email === data.email) {
          this.app.throw(409, "邮箱已被其他用户使用", 10002);
        }
      }
    }

    const updated: User = {
      ...user,
      ...data,
      updatedAt: new Date().toISOString(),
    };

    this.users.set(id, updated);
    this.logger.info({ userId: id }, "用户更新成功");

    return updated;
  }

  /**
   * 删除用户
   */
  async delete(id: string): Promise<void> {
    this.logger.info({ userId: id }, "删除用户");

    if (!this.users.has(id)) {
      this.app.throw(404, "用户不存在");
    }

    this.users.delete(id);
    this.logger.info({ userId: id }, "用户删除成功");
  }

  /**
   * 统计用户数量
   */
  async count(): Promise<number> {
    return this.users.size;
  }
}

Tip

VextJS 的服务层通过约定式目录自动加载。将 class 或对象放在 src/services/ 目录下，框架会自动实例化并注入到 app.services 中。文件名即服务名：user.ts → app.services.user。

服务的 constructor 接收 app: VextApp 参数，可以访问 app.logger、app.config、app.throw 等框架能力。

5. 路由

根路由（健康检查）

// src/routes/index.ts
import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  // GET / → 健康检查
  app.get(
    "/",
    {
      docs: {
        summary: "健康检查",
        tags: ["基础"],
      },
    },
    async (_req, res) => {
      const userCount = await app.services.user.count();
      res.json({
        status: "ok",
        uptime: Math.floor(process.uptime()),
        users: userCount,
        timestamp: new Date().toISOString(),
      });
    },
  );
});

用户路由（完整 CRUD）

// src/routes/users.ts
import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // GET /users/list — 分页查询用户列表（公开）
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.get(
    "/list",
    {
      validate: {
        query: {
          page: "number:1-", // 页码，最小值 1
          limit: "number:1-100", // 每页条数，1-100
          keyword: "string?", // 搜索关键词（可选）
        },
      },
      docs: {
        summary: "用户列表",
        description: "分页查询用户列表，支持按姓名或邮箱模糊搜索。",
        tags: ["用户"],
        responses: {
          200: {
            description: "查询成功",
            example: {
              items: [
                {
                  id: "1",
                  name: "Alice",
                  email: "alice@example.com",
                  role: "admin",
                },
              ],
              total: 3,
              page: 1,
              limit: 10,
              totalPages: 1,
            },
          },
        },
      },
    },
    async (req, res) => {
      const { page, limit, keyword } = req.valid("query");
      const result = await app.services.user.findAll({ page, limit, keyword });
      res.json(result);
    },
  );

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // GET /users/:id — 根据 ID 查询用户（公开）
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.get(
    "/:id",
    {
      validate: {
        param: { id: "string:1-" },
      },
      docs: {
        summary: "获取用户详情",
        tags: ["用户"],
        responses: {
          200: { description: "查询成功" },
          404: { description: "用户不存在" },
        },
      },
    },
    async (req, res) => {
      const { id } = req.valid("param");
      const user = await app.services.user.findById(id);

      if (!user) {
        app.throw(404, "用户不存在");
      }

      res.json(user);
    },
  );

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // POST /users — 创建用户（需认证）
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.post(
    "/",
    {
      validate: {
        body: {
          name: "string:1-50", // 必填，长度 1-50
          email: "email", // 必填，邮箱格式
          age: "number:0-200?", // 可选，0-200
          role: "enum:admin,user?", // 可选，枚举值
        },
      },
      middlewares: ["auth"],
      docs: {
        summary: "创建用户",
        description: "创建一个新用户。需要 Bearer Token 认证。",
        tags: ["用户"],
        responses: {
          201: {
            description: "创建成功",
            example: {
              id: "4",
              name: "Diana",
              email: "diana@example.com",
              role: "user",
              createdAt: "2026-03-05T00:00:00.000Z",
              updatedAt: "2026-03-05T00:00:00.000Z",
            },
          },
          400: { description: "参数校验失败" },
          401: { description: "未认证" },
          409: { description: "邮箱已注册" },
        },
      },
    },
    async (req, res) => {
      const body = req.valid("body");

      app.logger.info(
        { operator: req.user?.id, email: body.email },
        "操作员创建用户",
      );

      const user = await app.services.user.create(body);
      res.json(user, 201);
    },
  );

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // PUT /users/:id — 更新用户（需认证）
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.put(
    "/:id",
    {
      validate: {
        param: { id: "string:1-" },
        body: {
          name: "string:1-50?", // 可选
          email: "email?", // 可选
          age: "number:0-200?", // 可选
        },
      },
      middlewares: ["auth"],
      docs: {
        summary: "更新用户",
        description:
          "更新指定用户的信息。需要 Bearer Token 认证。只需传入需要更新的字段。",
        tags: ["用户"],
        responses: {
          200: { description: "更新成功" },
          400: { description: "参数校验失败" },
          401: { description: "未认证" },
          404: { description: "用户不存在" },
          409: { description: "邮箱已被其他用户使用" },
        },
      },
    },
    async (req, res) => {
      const { id } = req.valid("param");
      const body = req.valid("body");

      app.logger.info(
        { operator: req.user?.id, targetUser: id },
        "操作员更新用户",
      );

      const user = await app.services.user.update(id, body);
      res.json(user);
    },
  );

  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  // DELETE /users/:id — 删除用户（需认证）
  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  app.delete(
    "/:id",
    {
      validate: {
        param: { id: "string:1-" },
      },
      middlewares: ["auth"],
      docs: {
        summary: "删除用户",
        description: "删除指定用户。需要 Bearer Token 认证。此操作不可逆。",
        tags: ["用户"],
        responses: {
          204: { description: "删除成功（无响应体）" },
          401: { description: "未认证" },
          404: { description: "用户不存在" },
        },
      },
    },
    async (req, res) => {
      const { id } = req.valid("param");

      app.logger.info(
        { operator: req.user?.id, targetUser: id },
        "操作员删除用户",
      );

      await app.services.user.delete(id);
      res.status(204).json(null);
    },
  );
});

6. 入口文件

// src/index.ts
import { bootstrap } from "vextjs";

bootstrap().catch((err) => {
  console.error("启动失败:", err);
  process.exit(1);
});

7. 测试

// test/users.test.ts
import { describe, it, expect, beforeEach, afterEach } from "vitest";
import { createTestApp } from "vextjs/testing";
import type { TestApp } from "vextjs";

describe("用户 CRUD", () => {
  let testApp: TestApp;
  const AUTH_TOKEN = "user-1-admin"; // 模拟管理员 token

  beforeEach(async () => {
    testApp = await createTestApp();
  });

  afterEach(async () => {
    await testApp?.close();
  });

  // ── 查询 ──────────────────────────────────────

  describe("GET /users/list", () => {
    it("应返回分页用户列表", async () => {
      const res = await testApp.request
        .get("/users/list")
        .query({ page: 1, limit: 10 });

      expect(res.status).toBe(200);
      expect(res.body.code).toBe(0);
      expect(Array.isArray(res.body.data.items)).toBe(true);
      expect(res.body.data.total).toBeGreaterThan(0);
      expect(res.body.data.page).toBe(1);
    });

    it("支持关键词搜索", async () => {
      const res = await testApp.request
        .get("/users/list")
        .query({ page: 1, limit: 10, keyword: "alice" });

      expect(res.status).toBe(200);
      expect(res.body.data.items.length).toBe(1);
      expect(res.body.data.items[0].name).toBe("Alice");
    });

    it("分页参数校验失败应返回 400", async () => {
      const res = await testApp.request
        .get("/users/list")
        .query({ page: 0, limit: 10 }); // page 最小值为 1

      expect(res.status).toBe(400);
    });
  });

  describe("GET /users/:id", () => {
    it("存在时应返回用户详情", async () => {
      const res = await testApp.request.get("/users/1");

      expect(res.status).toBe(200);
      expect(res.body.data).toMatchObject({
        id: "1",
        name: "Alice",
        email: "alice@example.com",
      });
    });

    it("不存在时应返回 404", async () => {
      const res = await testApp.request.get("/users/999");

      expect(res.status).toBe(404);
      expect(res.body.message).toBe("用户不存在");
    });
  });

  // ── 创建 ──────────────────────────────────────

  describe("POST /users", () => {
    it("认证后应成功创建用户", async () => {
      const res = await testApp.request
        .post("/users")
        .set("Authorization", `Bearer ${AUTH_TOKEN}`)
        .send({
          name: "Diana",
          email: "diana@example.com",
          age: 25,
        });

      expect(res.status).toBe(201);
      expect(res.body.code).toBe(0);
      expect(res.body.data).toMatchObject({
        name: "Diana",
        email: "diana@example.com",
        age: 25,
        role: "user",
      });
      expect(res.body.data.id).toBeDefined();
      expect(res.body.data.createdAt).toBeDefined();
    });

    it("未认证应返回 401", async () => {
      const res = await testApp.request
        .post("/users")
        .send({ name: "Test", email: "test@example.com" });

      expect(res.status).toBe(401);
    });

    it("邮箱重复应返回 409", async () => {
      const res = await testApp.request
        .post("/users")
        .set("Authorization", `Bearer ${AUTH_TOKEN}`)
        .send({
          name: "Alice Copy",
          email: "alice@example.com", // 已存在
        });

      expect(res.status).toBe(409);
      expect(res.body.code).toBe(10001);
    });

    it("name 为空应返回 400", async () => {
      const res = await testApp.request
        .post("/users")
        .set("Authorization", `Bearer ${AUTH_TOKEN}`)
        .send({
          name: "",
          email: "new@example.com",
        });

      expect(res.status).toBe(400);
      expect(res.body.errors).toBeDefined();
    });

    it("email 格式无效应返回 400", async () => {
      const res = await testApp.request
        .post("/users")
        .set("Authorization", `Bearer ${AUTH_TOKEN}`)
        .send({
          name: "Valid Name",
          email: "not-an-email",
        });

      expect(res.status).toBe(400);
    });
  });

  // ── 更新 ──────────────────────────────────────

  describe("PUT /users/:id", () => {
    it("认证后应成功更新用户", async () => {
      const res = await testApp.request
        .put("/users/1")
        .set("Authorization", `Bearer ${AUTH_TOKEN}`)
        .send({ name: "Alice Updated" });

      expect(res.status).toBe(200);
      expect(res.body.data.name).toBe("Alice Updated");
      expect(res.body.data.email).toBe("alice@example.com"); // 未修改的字段保持不变
    });

    it("更新不存在的用户应返回 404", async () => {
      const res = await testApp.request
        .put("/users/999")
        .set("Authorization", `Bearer ${AUTH_TOKEN}`)
        .send({ name: "Ghost" });

      expect(res.status).toBe(404);
    });

    it("邮箱冲突应返回 409", async () => {
      const res = await testApp.request
        .put("/users/1")
        .set("Authorization", `Bearer ${AUTH_TOKEN}`)
        .send({ email: "bob@example.com" }); // Bob 的邮箱

      expect(res.status).toBe(409);
      expect(res.body.code).toBe(10002);
    });
  });

  // ── 删除 ──────────────────────────────────────

  describe("DELETE /users/:id", () => {
    it("认证后应成功删除用户", async () => {
      const res = await testApp.request
        .delete("/users/2")
        .set("Authorization", `Bearer ${AUTH_TOKEN}`);

      expect(res.status).toBe(204);

      // 确认已删除
      const getRes = await testApp.request.get("/users/2");
      expect(getRes.status).toBe(404);
    });

    it("删除不存在的用户应返回 404", async () => {
      const res = await testApp.request
        .delete("/users/999")
        .set("Authorization", `Bearer ${AUTH_TOKEN}`);

      expect(res.status).toBe(404);
    });

    it("未认证应返回 401", async () => {
      const res = await testApp.request.delete("/users/1");

      expect(res.status).toBe(401);
    });
  });

  // ── 健康检查 ──────────────────────────────────

  describe("GET /", () => {
    it("应返回服务状态", async () => {
      const res = await testApp.request.get("/");

      expect(res.status).toBe(200);
      expect(res.body.data).toMatchObject({
        status: "ok",
        users: expect.any(Number),
      });
    });
  });
});

8. 运行

开发模式

pnpm dev

启动后可以：

访问 http://localhost:3000/ 查看健康检查
访问 http://localhost:3000/docs 查看自动生成的 Scalar API 文档
使用 curl 测试各个接口

运行测试

pnpm test

9. 接口测试

# 健康检查
curl http://localhost:3000/
# → {"code":0,"data":{"status":"ok","users":3,...},"requestId":"..."}

# 查询用户列表
curl "http://localhost:3000/users/list?page=1&limit=10"
# → {"code":0,"data":{"items":[...],"total":3,"page":1,"limit":10,"totalPages":1},"requestId":"..."}

# 搜索用户
curl "http://localhost:3000/users/list?page=1&limit=10&keyword=alice"
# → {"code":0,"data":{"items":[{"id":"1","name":"Alice",...}],...},"requestId":"..."}

# 查询单个用户
curl http://localhost:3000/users/1
# → {"code":0,"data":{"id":"1","name":"Alice","email":"alice@example.com",...},"requestId":"..."}

# 创建用户（需认证）
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{"name":"Diana","email":"diana@example.com","age":25}'
# → 201 {"code":0,"data":{"id":"4","name":"Diana",...},"requestId":"..."}

# 更新用户（需认证）
curl -X PUT http://localhost:3000/users/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{"name":"Alice Updated"}'
# → {"code":0,"data":{"id":"1","name":"Alice Updated",...},"requestId":"..."}

# 删除用户（需认证）
curl -X DELETE http://localhost:3000/users/2 \
  -H "Authorization: Bearer user-1-admin"
# → 204 No Content

# 未认证访问受保护接口
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Test","email":"test@example.com"}'
# → 401 {"code":-1,"message":"未提供认证令牌","requestId":"..."}

# 参数校验失败
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer user-1-admin" \
  -d '{"name":"","email":"invalid"}'
# → 400 {"code":-1,"message":"Validation failed","errors":[...],"requestId":"..."}

10. 关键概念总结

请求-响应流程

客户端请求
  → requestId 中间件（生成/透传请求 ID）
  → CORS 中间件（处理跨域）
  → body-parser 中间件（解析请求体）
  → access-log 中间件（记录开始时间）
  → rate-limit 中间件（速率限制检查）
  → response-wrapper 中间件（开启出口包装）
  → auth 中间件（验证 token，注入 req.user）  ← 仅受保护路由
  → validate 中间件（参数校验）              ← 有 validate 配置时
  → handler（业务逻辑）
  → 出口包装（{ code: 0, data, requestId }）
  → 响应返回

错误处理流程

handler 中 app.throw(404, '用户不存在')
  → 抛出 HttpError
  → error-handler 中间件捕获
  → 转换为标准错误响应
  → {"code":-1,"message":"用户不存在","requestId":"..."}
  → HTTP 404

设计模式

模式	说明
三段式路由	`app.method(path, options, handler)` — 声明式配置
服务层分离	业务逻辑封装在 `src/services/` 中，路由只做编排
中间件白名单	路由级中间件必须在 `config.middlewares` 中声明
声明式校验	`validate` 使用 schema-dsl DSL 语法，自动类型转换
统一错误处理	`app.throw()` 抛出错误，框架自动转为标准格式
出口包装	所有成功响应自动包装为 `{ code: 0, data, requestId }`
OpenAPI 自动生成	从 `validate` 和 `docs` 配置自动生成 API 文档

下一步

📖 Zod 校验集成 — 使用 Zod 替换内置的 schema-dsl 校验
📖 Drizzle ORM 集成 — 接入 Drizzle ORM 实现真实数据库操作
📖 Prisma ORM 集成 — 接入 Prisma ORM 实现真实数据库操作
📖 测试 — 深入了解 VextJS 测试工具的高级用法
📖 OpenAPI 文档 — 深入了解 OpenAPI 自动生成的配置选项

#CRUD API

#项目结构

#1. 初始化项目

#2. 配置

#3. 认证中间件

#4. 服务层

#5. 路由

#根路由（健康检查）

#用户路由（完整 CRUD）

#6. 入口文件

#7. 测试

#8. 运行

#开发模式

#运行测试

#9. 接口测试

#10. 关键概念总结

#请求-响应流程

#错误处理流程

#设计模式

#下一步