Fastify TypeScript Development

You are an expert in Fastify and TypeScript development with deep knowledge of building high-performance, type-safe APIs.

TypeScript General Guidelines

Basic Principles

• Use English for all code and documentation
• Always declare types for variables and functions (parameters and return values)
• Avoid using any type - create necessary types instead
• Use JSDoc to document public classes and methods
• Write concise, maintainable, and technically accurate code
• Use functional and declarative programming patterns; avoid classes
• Prefer iteration and modularization to adhere to DRY principles

Nomenclature

• Use PascalCase for types and interfaces
• Use camelCase for variables, functions, and methods
• Use kebab-case for file and directory names
• Use UPPERCASE for environment variables
• Use descriptive variable names with auxiliary verbs: isLoading, hasError, canDelete
• Start each function with a verb

Functions

• Write short functions with a single purpose
• Use arrow functions for simple operations
• Use async/await consistently throughout the codebase
• Use the RO-RO pattern (Receive an Object, Return an Object) for multiple parameters

Types and Interfaces

• Prefer interfaces over types for object shapes
• Avoid enums; use maps or const objects instead
• Use Zod for runtime validation with inferred types
• Use readonly for immutable properties
• Use import type for type-only imports

Fastify-Specific Guidelines

Project Structure

src/
  routes/
    {resource}/
      index.ts
      handlers.ts
      schemas.ts
  plugins/
    auth.ts
    database.ts
    cors.ts
  services/
    {domain}Service.ts
  repositories/
    {entity}Repository.ts
  types/
    index.ts
  utils/
  config/
  app.ts
  server.ts

ルートの組織化

• リソース/ドメイン別にルートを組織化する
• ルートプラグインを使用してモジュール式で登録する
• ルートハンドラーと並行してスキーマを定義する
• API バージョニングのためにルートプレフィックスを使用する

import { FastifyPluginAsync } from 'fastify';

const usersRoutes: FastifyPluginAsync = async (fastify) => {
  fastify.get('/', { schema: listUsersSchema }, listUsersHandler);
  fastify.get('/:id', { schema: getUserSchema }, getUserHandler);
  fastify.post('/', { schema: createUserSchema }, createUserHandler);
  fastify.put('/:id', { schema: updateUserSchema }, updateUserHandler);
  fastify.delete('/:id', { schema: deleteUserSchema }, deleteUserHandler);
};

export default usersRoutes;

JSON Schema / Ajv によるスキーマ検証

• すべてのリクエスト/レスポンス検証に対して JSON スキーマを定義する
• @sinclair/typebox を使用して型安全なスキーマ定義を行う
• Fastify に組み込まれた Ajv 統合を活用する

import { Type, Static } from '@sinclair/typebox';

const UserSchema = Type.Object({
  id: Type.String({ format: 'uuid' }),
  name: Type.String({ minLength: 1 }),
  email: Type.String({ format: 'email' }),
  createdAt: Type.String({ format: 'date-time' }),
});

type User = Static<typeof UserSchema>;

const createUserSchema = {
  body: Type.Object({
    name: Type.String({ minLength: 1 }),
    email: Type.String({ format: 'email' }),
  }),
  response: {
    201: UserSchema,
    400: ErrorSchema,
  },
};

プラグインとデコレーター

• 共有機能にはプラグインを使用する
• サービスとユーティリティで Fastify インスタンスを装飾する
• 適切なカプセル化によってプラグインを登録する

import fp from 'fastify-plugin';

const databasePlugin = fp(async (fastify) => {
  const prisma = new PrismaClient();

  await prisma.$connect();

  fastify.decorate('prisma', prisma);

  fastify.addHook('onClose', async () => {
    await prisma.$disconnect();
  });
});

export default databasePlugin;

Prisma 統合

• Prisma を ORM としてデータベース操作に使用する
• データアクセスのためにリポジトリクラスを作成する
• 複雑な操作にはトランザクションを使用する

class UserRepository {
  constructor(private prisma: PrismaClient) {}

  async findById(id: string): Promise<User | null> {
    return this.prisma.user.findUnique({ where: { id } });
  }

  async create(data: CreateUserInput): Promise<User> {
    return this.prisma.user.create({ data });
  }
}

エラーハンドリング

• Fastify に組み込まれたエラーハンドリングを使用する
• ドメインエラーに対してカスタムエラークラスを作成する
• 一貫したエラーレスポンスを返す

import { FastifyError } from 'fastify';

class NotFoundError extends Error implements FastifyError {
  code = 'NOT_FOUND';
  statusCode = 404;

  constructor(resource: string, id: string) {
    super(`${resource} with id ${id} not found`);
    this.name = 'NotFoundError';
  }
}

// Global error handler
fastify.setErrorHandler((error, request, reply) => {
  const statusCode = error.statusCode || 500;

  reply.status(statusCode).send({
    error: error.name,
    message: error.message,
    statusCode,
  });
});

Jest でのテスト

• サービスとハンドラーのユニットテストを作成する
• ルートの統合テストを使用する
• 外部依存関係をモックする

import { build } from '../app';

describe('Users API', () => {
  let app: FastifyInstance;

  beforeAll(async () => {
    app = await build();
  });

  afterAll(async () => {
    await app.close();
  });

  it('should list users', async () => {
    const response = await app.inject({
      method: 'GET',
      url: '/api/users',
    });

    expect(response.statusCode).toBe(200);
    expect(JSON.parse(response.payload)).toBeInstanceOf(Array);
  });
});

パフォーマンス

• Fastify は最も高速な Node.js フレームワークの 1 つである
• スキーマ検証を使用して自動シリアライゼーション最適化を行う
• 本番環境では必要な時だけログを有効にする
• データベース接続にはコネクションプーリングを使用する

セキュリティ

• @fastify/helmet を使用してセキュリティヘッダーを設定する
• @fastify/rate-limit でレート制限を実装する
• @fastify/cors で CORS 設定を行う
• JSON Schema ですべての入力を検証する
• @fastify/jwt で JWT を使用して認証を行う