z.string().min(2).max(100),

分类: 开发与编程 | 上传者: FairArena | 下载: 0 | 版本: v1.0（最新）
Comprehensive backend architecture patterns for scalable, maintainable, and secure server-side applications with microservices, API design, and data modeling.
更新日志: Source: GitHub https://github.com/FairArena/FairArena
目录结构

当前层级: copilot-skill/backend-architecture/
📄 SKILL.md 20.1 KB
SKILL.md

# Backend Architecture & System Design

## Overview

Comprehensive backend architecture patterns for scalable, maintainable, and secure server-side applications with microservices, API design, and data modeling.

## API Architecture Patterns

### 1. RESTful API Design

```typescript
// routes/v1/userRoutes.ts
import { Router } from 'express';
import { UserController } from '../controllers/UserController';
import { authenticate, authorize } from '../middleware/auth';
import { validateRequest } from '../middleware/validation';
import { rateLimit } from '../middleware/rateLimit';

const router = Router();

// Resource-based routing with proper HTTP methods
router.get(
  '/users',
  authenticate,
  authorize(['users:read']),
  rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }),
  validateRequest({
    query: z.object({
      page: z.number().min(1).default(1),
      limit: z.number().min(1).max(100).default(20),
      search: z.string().optional(),
      sortBy: z.enum(['createdAt', 'name', 'email']).default('createdAt'),
      sortOrder: z.enum(['asc', 'desc']).default('desc'),
    }),
  }),
  UserController.getUsers,
);

router.post(
  '/users',
  authenticate,
  authorize(['users:create']),
  validateRequest({
    body: z.object({
      email: z.string().email(),
      name: z.string().min(2).max(100),
      role: z.enum(['user', 'admin']).default('user'),
    }),
  }),
  UserController.createUser,
);

router.get(
  '/users/:id',
  authenticate,
  authorize(['users:read']),
  validateRequest({
    params: z.object({ id: z.string().uuid() }),
  }),
  UserController.getUserById,
);

router.patch(
  '/users/:id',
  authenticate,
  authorize(['users:update']),
  validateRequest({
    params: z.object({ id: z.string().uuid() }),
    body: z.object({
      name: z.string().min(2).max(100).optional(),
      email: z.string().email().optional(),
    }),
  }),
  UserController.updateUser,
);

router.delete(
  '/users/:id',
  authenticate,
  authorize(['users:delete']),
  validateRequest({
    params: z.object({ id: z.string().uuid() }),
  }),
  UserController.deleteUser,
);

export { router as userRoutes };
```

### 2. GraphQL API Design

```typescript
// graphql/schema.ts
import { gql } from 'apollo-server-express';

export const typeDefs = gql`
  type User {
    id: ID!
    email: String!
    name: String!
    profile: Profile
    posts: [Post!]!
    createdAt: DateTime!
    updatedAt: DateTime!
  }

  type Profile {
    id: ID!
    bio: String
    avatar: String
    location: String
  }

  type Post {
    id: ID!
    title: String!
    content: String!
    author: User!
    tags: [String!]!
    published: Boolean!
    createdAt: DateTime!
    updatedAt: DateTime!
  }

  type Query {
    users(limit: Int, offset: Int): [User!]!
    user(id: ID!): User
    posts(limit: Int, offset: Int, published: Boolean): [Post!]!
    post(id: ID!): Post
  }

  type Mutation {
    createUser(input: CreateUserInput!): User!
    updateUser(id: ID!, input: UpdateUserInput!): User!
    deleteUser(id: ID!): Boolean!

    createPost(input: CreatePostInput!): Post!
    updatePost(id: ID!, input: UpdatePostInput!): Post!
    deletePost(id: ID!): Boolean!
  }

  input CreateUserInput {
    email: String!
    name: String!
  }

  input UpdateUserInput {
    name: String
    email: String
  }

  input CreatePostInput {
    title: String!
    content: String!
    tags: [String!]
    published: Boolean
  }

  input UpdatePostInput {
    title: String
    content: String
    tags: [String!]
    published: Boolean
  }
`;

// resolvers/userResolver.ts
export const userResolvers = {
  Query: {
    users: async (_: any, { limit = 20, offset = 0 }: any, { dataSources }: any) => {
      return dataSources.userAPI.getUsers({ limit, offset });
    },
    user: async (_: any, { id }: any, { dataSources }: any) => {
      return dataSources.userAPI.getUserById(id);
    },
  },
  Mutation: {
    createUser: async (_: any, { input }: any, { dataSources }: any) => {
      return dataSources.userAPI.createUser(input);
    },
    updateUser: async (_: any, { input }: any, { dataSources }: any) => {
      return dataSources.userAPI.updateUser(input);
    },
  },
  User: {
    posts: async (user: any, _: any, { dataSources }: any) => {
      return dataSources.postAPI.getPostsByUserId(user.id);
    },
  },
};
```

## Microservices Architecture

### 3. Service Decomposition

```typescript
// services/user-service/src/index.ts
import express from 'express';
import { createUserRoutes } from './routes/userRoutes';
import { createDatabaseConnection } from './database/connection';
import { createMessageBroker } from './message-broker';
import { createMetricsCollector } from './monitoring/metrics';

const app = express();

// Service configuration
const SERVICE_CONFIG = {
  name: 'user-service',
  version: '1.0.0',
  port: process.env.PORT || 3001,
  database: {
    host: process.env.DB_HOST,
    port: process.env.DB_PORT,
    database: process.env.DB_NAME,
    user: process.env.DB_USER,
    password: process.env.DB_PASSWORD,
  },
  messageBroker: {
    url: process.env.MESSAGE_BROKER_URL,
  },
};

// Initialize dependencies
const database = createDatabaseConnection(SERVICE_CONFIG.database);
const messageBroker = createMessageBroker(SERVICE_CONFIG.messageBroker);
const metrics = createMetricsCollector(SERVICE_CONFIG.name);

// Middleware
app.use(express.json());
app.use(metrics.middleware);

// Routes
app.use('/api/v1', createUserRoutes(database, messageBroker));

// Health check
app.get('/health', async (req, res) => {
  const health = await checkServiceHealth(database, messageBroker);
  res.status(health.status === 'healthy' ? 200 : 503).json(health);
});

// Graceful shutdown
process.on('SIGTERM', async () => {
  await database.close();
  await messageBroker.close();
  process.exit(0);
});

app.listen(SERVICE_CONFIG.port, () => {
  console.log(`${SERVICE_CONFIG.name} listening on port ${SERVICE_CONFIG.port}`);
});
```

### 4. Event-Driven Communication

```typescript
// message-broker/index.ts
import { Connection, Channel, connect } from 'amqplib';

interface MessageBroker {
  publish: (exchange: string, routingKey: string, message: any) => Promise<void>;
  subscribe: (queue: string, handler: (message: any) => Promise<void>) => Promise<void>;
  close: () => Promise<void>;
}

export const createMessageBroker = (config: { url: string }): MessageBroker => {
  let connection: Connection;
  let channel: Channel;

  const connect = async () => {
    connection = await amqp.connect(config.url);
    channel = await connection.createChannel();

    // Declare exchanges
    await channel.assertExchange('user-events', 'topic', { durable: true });
    await channel.assertExchange('post-events', 'topic', { durable: true });
  };

  return {
    publish: async (exchange: string, routingKey: string, message: any) => {
      if (!channel) await connect();
      await channel.publish(exchange, routingKey, Buffer.from(JSON.stringify(message)), {
        persistent: true,
      });
    },

    subscribe: async (queue: string, handler: (message: any) => Promise<void>) => {
      if (!channel) await connect();

      const { queue: queueName } = await channel.assertQueue(queue, { durable: true });
      await channel.bindQueue(queueName, 'user-events', '#');

      channel.consume(queueName, async (msg) => {
        if (msg) {
          try {
            const message = JSON.parse(msg.content.toString());
            await handler(message);
            channel.ack(msg);
          } catch (error) {
            console.error('Message processing failed:', error);
            channel.nack(msg, false, false); // Don't requeue
          }
        }
      });
    },

    close: async () => {
      if (channel) await channel.close();
      if (connection) await connection.close();
    },
  };
};

// Event publishing
export const publishUserEvent = async (broker: MessageBroker, event: UserEvent) => {
  await broker.publish('user-events', `user.${event.type}`, event);
};

// Event types
export interface UserEvent {
  type: 'created' | 'updated' | 'deleted';
  userId: string;
  data: any;
  timestamp: Date;
  correlationId: string;
}
```

## Data Architecture

### 5. Database Design Patterns

```sql
-- schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        String   @id @default(cuid())
  email     String   @unique
  name      String
  role      UserRole @default(USER)
  profile   Profile?
  posts     Post[]
  sessions  Session[]
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@map("users")
}

model Profile {
  id        String   @id @default(cuid())
  userId    String   @unique
  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  bio       String?
  avatar    String?
  location  String?
  website   String?
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt

  @@map("profiles")
}

model Post {
  id        String     @id @default(cuid())
  authorId  String
  author    User       @relation(fields: [authorId], references: [id], onDelete: Cascade)
  title     String
  content   String     @db.Text
  published Boolean    @default(false)
  tags      String[]   // PostgreSQL array
  views     Int        @default(0)
  likes     Int        @default(0)
  createdAt DateTime   @default(now())
  updatedAt DateTime   @updatedAt

  @@map("posts")
}

model Session {
  id        String   @id @default(cuid())
  userId    String
  user      User     @relation(fields: [userId], references: [id], onDelete: Cascade)
  token     String   @unique
  expiresAt DateTime
  createdAt DateTime @default(now())

  @@map("sessions")
}

enum UserRole {
  USER
  ADMIN
  MODERATOR
}
```

### 6. Repository Pattern

```typescript
// repositories/userRepository.ts
import { PrismaClient, User, Prisma } from '@prisma/client';

export interface UserRepository {
  findById(id: string): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
  findMany(options: FindManyOptions): Promise<User[]>;
  create(data: Prisma.UserCreateInput): Promise<User>;
  update(id: string, data: Prisma.UserUpdateInput): Promise<User>;
  delete(id: string): Promise<User>;
  count(options?: Prisma.UserCountArgs): Promise<number>;
}

interface FindManyOptions {
  where?: Prisma.UserWhereInput;
  orderBy?: Prisma.UserOrderByWithRelationInput;
  skip?: number;
  take?: number;
  include?: Prisma.UserInclude;
}

export class PrismaUserRepository implements UserRepository {
  constructor(private prisma: PrismaClient) {}

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

  async findByEmail(email: string): Promise<User | null> {
    return this.prisma.user.findUnique({
      where: { email },
      include: { profile: true },
    });
  }

  async findMany(options: FindManyOptions): Promise<User[]> {
    return this.prisma.user.findMany({
      where: options.where,
      orderBy: options.orderBy,
      skip: options.skip,
      take: options.take,
      include: options.include,
    });
  }

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

  async update(id: string, data: Prisma.UserUpdateInput): Promise<User> {
    return this.prisma.user.update({
      where: { id },
      data,
    });
  }

  async delete(id: string): Promise<User> {
    return this.prisma.user.delete({
      where: { id },
    });
  }

  async count(options?: Prisma.UserCountArgs): Promise<number> {
    return this.prisma.user.count(options);
  }
}
```

## Service Layer Architecture

### 7. Domain-Driven Design

```typescript
// domain/entities/User.ts
export class User {
  private constructor(
    public readonly id: string,
    public email: string,
    public name: string,
    public role: UserRole,
    public readonly createdAt: Date,
    public updatedAt: Date,
    private profile?: Profile,
  ) {}

  static create(props: CreateUserProps): User {
    const id = generateId();
    const now = new Date();

    return new User(id, props.email, props.name, props.role || UserRole.USER, now, now);
  }

  updateProfile(profile: Profile): void {
    this.profile = profile;
    this.updatedAt = new Date();
  }

  canUpdate(other: User): boolean {
    return this.role === UserRole.ADMIN || this.id === other.id;
  }

  toJSON() {
    return {
      id: this.id,
      email: this.email,
      name: this.name,
      role: this.role,
      profile: this.profile,
      createdAt: this.createdAt,
      updatedAt: this.updatedAt,
    };
  }
}

export enum UserRole {
  USER = 'USER',
  ADMIN = 'ADMIN',
  MODERATOR = 'MODERATOR',
}

export interface CreateUserProps {
  email: string;
  name: string;
  role?: UserRole;
}
```

### 8. Use Case Pattern

```typescript
// use-cases/CreateUser.ts
import { UserRepository } from '../repositories/UserRepository';
import { User, CreateUserProps } from '../domain/User';
import { EmailAlreadyExistsError } from '../errors/EmailAlreadyExistsError';

export interface CreateUserRequest {
  email: string;
  name: string;
  role?: string;
}

export interface CreateUserResponse {
  user: User;
}

export class CreateUser {
  constructor(private userRepository: UserRepository) {}

  async execute(request: CreateUserRequest): Promise<CreateUserResponse> {
    // Validate input
    const { email, name, role } = request;

    // Check if email already exists
    const existingUser = await this.userRepository.findByEmail(email);
    if (existingUser) {
      throw new EmailAlreadyExistsError(email);
    }

    // Create user entity
    const user = User.create({
      email,
      name,
      role: (role as any) || undefined,
    });

    // Persist to database
    await this.userRepository.create({
      id: user.id,
      email: user.email,
      name: user.name,
      role: user.role,
      createdAt: user.createdAt,
      updatedAt: user.updatedAt,
    });

    return { user };
  }
}
```

## Controller Layer

### 9. Clean Architecture Controllers

```typescript
// controllers/UserController.ts
import { Request, Response } from 'express';
import { CreateUser } from '../use-cases/CreateUser';
import { GetUser } from '../use-cases/GetUser';
import { UpdateUser } from '../use-cases/UpdateUser';
import { DeleteUser } from '../use-cases/DeleteUser';
import { ListUsers } from '../use-cases/ListUsers';

export class UserController {
  constructor(
    private createUser: CreateUser,
    private getUser: GetUser,
    private updateUser: UpdateUser,
    private deleteUser: DeleteUser,
    private listUsers: ListUsers,
  ) {}

  async create(request: Request, response: Response): Promise<Response> {
    try {
      const { email, name, role } = request.body;

      const result = await this.createUser.execute({
        email,
        name,
        role,
      });

      return response.status(201).json({
        success: true,
        data: result.user.toJSON(),
      });
    } catch (error) {
      return this.handleError(error, response);
    }
  }

  async getById(request: Request, response: Response): Promise<Response> {
    try {
      const { id } = request.params;

      const result = await this.getUser.execute({ id });

      return response.json({
        success: true,
        data: result.user.toJSON(),
      });
    } catch (error) {
      return this.handleError(error, response);
    }
  }

  async update(request: Request, response: Response): Promise<Response> {
    try {
      const { id } = request.params;
      const { name, email } = request.body;

      const result = await this.updateUser.execute({
        id,
        name,
        email,
      });

      return response.json({
        success: true,
        data: result.user.toJSON(),
      });
    } catch (error) {
      return this.handleError(error, response);
    }
  }

  async delete(request: Request, response: Response): Promise<Response> {
    try {
      const { id } = request.params;

      await this.deleteUser.execute({ id });

      return response.status(204).send();
    } catch (error) {
      return this.handleError(error, response);
    }
  }

  async list(request: Request, response: Response): Promise<Response> {
    try {
      const { page = 1, limit = 20, search, sortBy, sortOrder } = request.query;

      const result = await this.listUsers.execute({
        page: Number(page),
        limit: Number(limit),
        search: search as string,
        sortBy: sortBy as string,
        sortOrder: sortOrder as 'asc' | 'desc',
      });

      return response.json({
        success: true,
        data: {
          users: result.users.map((u) => u.toJSON()),
          pagination: result.pagination,
        },
      });
    } catch (error) {
      return this.handleError(error, response);
    }
  }

  private handleError(error: any, response: Response): Response {
    if (error instanceof ValidationError) {
      return response.status(400).json({
        success: false,
        error: 'Validation failed',
        details: error.details,
      });
    }

    if (error instanceof NotFoundError) {
      return response.status(404).json({
        success: false,
        error: 'Resource not found',
      });
    }

    console.error('Unhandled error:', error);
    return response.status(500).json({
      success: false,
      error: 'Internal server error',
    });
  }
}
```

## Infrastructure Layer

### 10. Dependency Injection

```typescript
// container.ts
import { UserRepository } from './repositories/UserRepository';
import { PrismaUserRepository } from './repositories/PrismaUserRepository';
import { CreateUser } from './use-cases/CreateUser';
import { GetUser } from './use-cases/GetUser';
import { UserController } from './controllers/UserController';
import { PrismaClient } from '@prisma/client';

export class Container {
  private instances = new Map<string, any>();

  get prisma(): PrismaClient {
    if (!this.instances.has('prisma')) {
      this.instances.set('prisma', new PrismaClient());
    }
    return this.instances.get('prisma');
  }

  get userRepository(): UserRepository {
    if (!this.instances.has('userRepository')) {
      this.instances.set('userRepository', new PrismaUserRepository(this.prisma));
    }
    return this.instances.get('userRepository');
  }

  get createUser(): CreateUser {
    if (!this.instances.has('createUser')) {
      this.instances.set('createUser', new CreateUser(this.userRepository));
    }
    return this.instances.get('createUser');
  }

  get getUser(): GetUser {
    if (!this.instances.has('getUser')) {
      this.instances.set('getUser', new GetUser(this.userRepository));
    }
    return this.instances.get('getUser');
  }

  get userController(): UserController {
    if (!this.instances.has('userController')) {
      this.instances.set(
        'userController',
        new UserController(
          this.createUser,
          this.getUser,
          // ... other use cases
        ),
      );
    }
    return this.instances.get('userController');
  }
}

export const container = new Container();
```

## Best Practices

### Architecture Principles

1. **Single Responsibility**: Each class has one reason to change
2. **Dependency Inversion**: Depend on abstractions, not concretions
3. **Interface Segregation**: Clients depend only on methods they use
4. **Open/Closed**: Open for extension, closed for modification

### API Design Guidelines

1. **RESTful Resources**: Use nouns for endpoints, HTTP methods for actions
2. **Versioning**: Include API version in URL (/api/v1/)
3. **Consistent Responses**: Standard success/error response formats
4. **Pagination**: Implement cursor or offset-based pagination
5. **Filtering & Sorting**: Support query parameters for filtering and sorting

### Database Design Principles

1. **Normalization**: Eliminate data redundancy
2. **Indexing**: Index foreign keys and frequently queried columns
3. **Constraints**: Use database constraints for data integrity
4. **Migrations**: Version-controlled schema changes
5. **Performance**: Optimize queries and use appropriate data types

### Microservices Considerations

1. **Bounded Contexts**: Clear service boundaries
2. **Eventual Consistency**: Accept temporary inconsistencies
3. **API Gateway**: Single entry point for clients
4. **Service Discovery**: Dynamic service location
5. **Circuit Breakers**: Prevent cascade failures
登录后下载/点赞/收藏 ❤ 2 | ★ 0
z.string().min(2).max(100),

目录结构

SKILL.md

举报内容

提示
