adonisjs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

<essential_principles>

AdonisJS 6 Principles

AdonisJS 6 核心原则

TypeScript-first - Every request, service, and model is typed. Prefer explicit types over any.

TypeScript-first - 每个请求、服务和模型都有类型定义，优先使用显式类型而非any类型。

1. Thin Controllers, Focused Services

1. 轻量级控制器，聚焦服务层

Controllers orchestrate. Business logic lives in services or domain modules.

// app/controllers/users_controller.ts
import type { HttpContext } from "@adonisjs/core/http";
import CreateUserService from "#services/users/create_user_service";

export default class UsersController {
  async store({ request, response }: HttpContext) {
    const payload = await request.validateUsing(CreateUserService.validator);
    const user = await new CreateUserService().handle(payload);
    return response.created({ data: user });
  }
}

控制器仅负责协调调度，业务逻辑应存放在服务或领域模块中。

// app/controllers/users_controller.ts
import type { HttpContext } from "@adonisjs/core/http";
import CreateUserService from "#services/users/create_user_service";

export default class UsersController {
  async store({ request, response }: HttpContext) {
    const payload = await request.validateUsing(CreateUserService.validator);
    const user = await new CreateUserService().handle(payload);
    return response.created({ data: user });
  }
}

2. Validate Every Input with VineJS

2. 使用VineJS验证所有输入

Never trust request data. Validate on entry.

// app/validators/create_user.ts
import vine from "@vinejs/vine";

export const createUserValidator = vine.compile(
  vine.object({
    email: vine.string().email(),
    fullName: vine.string().minLength(2).maxLength(120),
    password: vine.string().minLength(8),
  }),
);

绝不信任请求数据，所有输入必须在入口处验证。

// app/validators/create_user.ts
import vine from "@vinejs/vine";

export const createUserValidator = vine.compile(
  vine.object({
    email: vine.string().email(),
    fullName: vine.string().minLength(2).maxLength(120),
    password: vine.string().minLength(8),
  }),
);

3. Lucid Models Own Persistence

3. Lucid Model 负责持久化操作

Use models for persistence and relationships. Keep queries in one place.

// app/models/user.ts
import { BaseModel, column } from "@adonisjs/lucid/orm";

export default class User extends BaseModel {
  @column({ isPrimary: true })
  declare id: number;

  @column()
  declare email: string;
}

使用Model处理数据持久化和关联关系，将数据库查询逻辑集中管理。

// app/models/user.ts
import { BaseModel, column } from "@adonisjs/lucid/orm";

export default class User extends BaseModel {
  @column({ isPrimary: true })
  declare id: number;

  @column()
  declare email: string;
}

4. Middleware for Cross-Cutting Concerns

4. 中间件处理横切关注点

Authentication, tenant scoping, and rate limiting belong in middleware.

// app/middleware/auth_middleware.ts
import type { HttpContext } from "@adonisjs/core/http";
import type { NextFn } from "@adonisjs/core/types/http";

export default class AuthMiddleware {
  async handle(ctx: HttpContext, next: NextFn) {
    await ctx.auth.check();
    return next();
  }
}

</essential_principles>

<intake> **What would you like to do?**

Build a new feature/endpoint
Debug an existing issue
Write/run tests
Optimize performance
Refactor code
Something else

Then read the matching workflow from
workflows/
and follow it. </intake>

<routing> | Response | Workflow | |----------|----------| | 1, "new", "create", "build", "feature", "endpoint", "api" | `workflows/build-feature.md` | | 2, "broken", "fix", "debug", "crash", "bug", "error" | `workflows/debug.md` | | 3, "test", "tests", "spec", "coverage" | `workflows/write-tests.md` | | 4, "slow", "optimize", "performance", "fast", "n+1" | `workflows/optimize-performance.md` | | 5, "refactor", "clean", "improve", "restructure" | `workflows/refactor.md` | | 6, other | Clarify, then select workflow or references | </routing>

<verification_loop>

身份验证、租户范围限制、请求频率限制等逻辑应放在中间件中实现。

// app/middleware/auth_middleware.ts
import type { HttpContext } from "@adonisjs/core/http";
import type { NextFn } from "@adonisjs/core/types/http";

export default class AuthMiddleware {
  async handle(ctx: HttpContext, next: NextFn) {
    await ctx.auth.check();
    return next();
  }
}

</essential_principles>

<intake> **你想要执行什么操作？**

构建新功能/接口
调试现有问题
编写/运行测试
优化性能
重构代码
其他操作

请阅读
workflows/
目录下对应的工作流文档并遵循其步骤操作。 </intake>

<routing> | 匹配关键词 | 对应工作流 | |----------|----------| | 1, "new", "create", "build", "feature", "endpoint", "api" | `workflows/build-feature.md` | | 2, "broken", "fix", "debug", "crash", "bug", "error" | `workflows/debug.md` | | 3, "test", "tests", "spec", "coverage" | `workflows/write-tests.md` | | 4, "slow", "optimize", "performance", "fast", "n+1" | `workflows/optimize-performance.md` | | 5, "refactor", "clean", "improve", "restructure" | `workflows/refactor.md` | | 6, other | 先明确需求，再选择对应工作流或参考文档 | </routing>

<verification_loop>

After Every Change

每次变更后需执行

bash

undefined

bash

undefined

1. Type check

1. 类型检查

pnpm typecheck

2. Run tests

2. 运行测试

node ace test tests/functional/changed.spec.ts

3. Lint

3. 代码检查

pnpm lint


Report: "Types: OK | Tests: X pass | Lint: clean"
</verification_loop>

<reference_index>

pnpm lint


报告示例：「类型检查：通过 | 测试：X个用例通过 | 代码检查：无问题」
</verification_loop>

<reference_index>

Domain Knowledge

领域知识文档

All in

references/

Architecture: architecture.md Models: models.md Controllers: controllers.md Serialization (DTOs): serialization.md Validations: validations-callbacks.md Background Jobs: background-jobs.md Performance: performance.md Testing: testing.md Multi-Tenant: multi-tenant.md Anti-Patterns: anti-patterns.md </reference_index>

<workflows_index>

所有文档均位于

references/

目录下：

架构设计： architecture.md 模型定义： models.md 控制器开发： controllers.md 序列化（DTO）： serialization.md 验证逻辑： validations-callbacks.md 后台任务： background-jobs.md 性能优化： performance.md 测试实践： testing.md 多租户实现： multi-tenant.md 反模式： anti-patterns.md </reference_index>

<workflows_index>

Workflows

工作流文档

All in

workflows/

File	Purpose
build-feature.md	Create new feature/endpoint from scratch
debug.md	Find and fix bugs
write-tests.md	Write and run tests
optimize-performance.md	Profile and speed up
refactor.md	Restructure code following patterns
</workflows_index>

所有文档均位于

workflows/

目录下：

文件	用途
build-feature.md	从0到1创建新功能/接口
debug.md	定位并修复Bug
write-tests.md	编写并运行测试用例
optimize-performance.md	性能分析与优化
refactor.md	遵循规范重构代码
</workflows_index>