Applicable Scenarios
- Implement endpoints according to the OpenAPI contract
- Unified layering across multiple languages / frameworks
- Interface parameter validation / DTO / response serialization
- HTTP middleware / interceptors / filters
- Cross-language common patterns (routing / controllers / services)
Core Principles
1. 分层清晰
Controller / Handler → 接收请求、调用服务、返回响应
Service / UseCase → 业务逻辑、事务编排
Repository / DAO → 数据访问
Domain Model → 业务实体
-
Controllers thin as paper Controller does not contain business logic
-
DTO and Entity separated Use DTOs to receive input / return responses ORM entities are not exposed directly to the outside
-
Validation at the boundary Input validation at the Controller layer (using framework mechanisms) Business rule validation at the Service layer
-
Unified error handling Global error handler + exception mapping
-
Do not call multiple Services in a Controller to assemble business logic Composition should be at the Service / UseCase layer
## 标准分层(语言无关)
```text
┌─────────────────────────────────────┐
│ Controller / Route Handler │ HTTP 入口
│ - 解析请求 / 校验 / 调用 Service │
│ - 返回 DTO / 错误转 HTTP 状态 │
└────────────────┬────────────────────┘
↓
┌─────────────────────────────────────┐
│ Service / UseCase │ 业务逻辑
│ - 事务边界 │
│ - 编排多个 Repository / 外部调用 │
│ - 业务规则校验 │
└────────────────┬────────────────────┘
↓
┌─────────────────────────────────────┐
│ Repository / DAO │ 数据访问
│ - 隐藏 ORM / SQL 细节 │
│ - 返回 Domain Model │
└────────────────┬────────────────────┘
↓
┌─────────────────────────────────────┐
│ Domain Model / Entity │ 业务实体
│ - 业务不变量 │
│ - 值对象 / 实体 │
└─────────────────────────────────────┘
Spring Boot Paradigm
// Controller
@RestController
@RequestMapping("/api/v1/orders")
public class OrderController {
private final OrderService orderService;
@PostMapping
public ResponseEntity<OrderDto> create(@Valid @RequestBody CreateOrderRequest req) {
OrderDto order = orderService.createOrder(req);
return ResponseEntity.status(HttpStatus.CREATED).body(order);
}
@GetMapping("/{id}")
public OrderDto get(@PathVariable Long id) {
return orderService.getOrder(id);
}
}
// Service
@Service
@Transactional
public class OrderService {
private final OrderRepository orderRepository;
private final UserRepository userRepository;
public OrderDto createOrder(CreateOrderRequest req) {
User user = userRepository.findById(req.getUserId())
.orElseThrow(() -> new ResourceNotFoundException("User not found"));
Order order = Order.create(user, req.getItems()); // 业务规则在 Domain
Order saved = orderRepository.save(order);
return OrderDto.from(saved);
}
}
// Repository
public interface OrderRepository extends JpaRepository<Order, Long> {
List<Order> findByUserIdAndStatus(Long userId, OrderStatus status);
}
// Global Error Handler
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException e) {
return ResponseEntity.status(404).body(new ErrorResponse("RESOURCE_NOT_FOUND", e.getMessage()));
}
}
NestJS Paradigm
// Controller
@Controller('api/v1/orders')
export class OrderController {
constructor(private orderService: OrderService) {}
@Post()
@HttpCode(201)
async create(@Body() dto: CreateOrderDto): Promise<OrderResponseDto> {
return this.orderService.createOrder(dto);
}
@Get(':id')
async get(@Param('id', ParseIntPipe) id: number): Promise<OrderResponseDto> {
return this.orderService.getOrder(id);
}
}
// DTO with class-validator
export class CreateOrderDto {
@IsInt() @IsPositive() userId: number;
@IsArray() @ValidateNested({ each: true }) @Type(() => OrderItemDto) items: OrderItemDto[];
}
// Service
@Injectable()
export class OrderService {
constructor(
@InjectRepository(Order) private orderRepo: Repository<Order>,
private userRepo: UserRepository,
) {}
@Transactional()
async createOrder(dto: CreateOrderDto): Promise<OrderResponseDto> {
const user = await this.userRepo.findOne(dto.userId);
if (!user) throw new NotFoundException('User not found');
const order = Order.create(user, dto.items);
return OrderResponseDto.from(await this.orderRepo.save(order));
}
}
// Global Exception Filter
@Catch(NotFoundException)
export class NotFoundFilter implements ExceptionFilter {
catch(exception: NotFoundException, host: ArgumentsHost) {
const ctx = host.switchToHttp();
const response = ctx.getResponse<Response>();
response.status(404).json({
error: { code: 'RESOURCE_NOT_FOUND', message: exception.message },
});
}
}
Django (DRF) Paradigm
# views.py
class OrderViewSet(viewsets.ModelViewSet):
queryset = Order.objects.all()
serializer_class = OrderSerializer
permission_classes = [IsAuthenticated]
def create(self, request):
serializer = CreateOrderSerializer(data=request.data)
serializer.is_valid(raise_exception=True)
order = OrderService.create_order(
user_id=serializer.validated_data['user_id'],
items=serializer.validated_data['items'],
)
return Response(OrderSerializer(order).data, status=201)
# serializers.py
class CreateOrderSerializer(serializers.Serializer):
user_id = serializers.IntegerField(min_value=1)
items = OrderItemSerializer(many=True)
# services.py
class OrderService:
@staticmethod
@transaction.atomic
def create_order(user_id, items):
user = User.objects.get(id=user_id)
order = Order.create(user=user, items=items)
order.save()
return order
# Custom exception handler (settings.py: REST_FRAMEWORK)
def custom_exception_handler(exc, context):
response = exception_handler(exc, context)
if response is not None:
response.data = {
'error': {
'code': exc.__class__.__name__,
'message': str(exc),
}
}
return response
FastAPI Paradigm
# main.py
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session
app = FastAPI()
@app.post("/api/v1/orders", status_code=201, response_model=OrderResponseDto)
async def create_order(
dto: CreateOrderDto,
db: Session = Depends(get_db),
current_user: User = Depends(get_current_user),
):
return await order_service.create_order(db, dto, current_user)
# DTO with Pydantic
class CreateOrderDto(BaseModel):
user_id: int = Field(gt=0)
items: list[OrderItemDto] = Field(min_length=1)
# Service
class OrderService:
@staticmethod
async def create_order(db: Session, dto: CreateOrderDto, user: User) -> OrderResponseDto:
order = Order.create(user, dto.items)
db.add(order)
db.commit()
db.refresh(order)
return OrderResponseDto.from_orm(order)
# Global exception handler
@app.exception_handler(ResourceNotFoundException)
async def not_found_handler(request, exc):
return JSONResponse(
status_code=404,
content={"error": {"code": "RESOURCE_NOT_FOUND", "message": str(exc)}},
)
Go (Gin) Paradigm
// handler/order.go
type OrderHandler struct {
service *service.OrderService
}
func (h *OrderHandler) Create(c *gin.Context) {
var req CreateOrderRequest
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(400, gin.H{"error": gin.H{"code": "VALIDATION_ERROR", "message": err.Error()}})
return
}
order, err := h.service.CreateOrder(c.Request.Context(), req)
if err != nil {
handleError(c, err)
return
}
c.JSON(201, OrderResponseDTO{}.FromEntity(order))
}
// service/order.go
func (s *OrderService) CreateOrder(ctx context.Context, req CreateOrderRequest) (*model.Order, error) {
user, err := s.userRepo.FindByID(ctx, req.UserID)
if err != nil {
return nil, fmt.Errorf("find user: %w", err)
}
order, err := model.NewOrder(user, req.Items)
if err != nil {
return nil, err
}
return s.orderRepo.Save(ctx, order)
}
// 路由 + 中间件
r := gin.Default()
r.Use(middleware.Logger())
r.Use(middleware.Recovery())
r.Use(middleware.Auth())
api := r.Group("/api/v1")
api.POST("/orders", h.Create)
api.GET("/orders/:id", h.Get)
Express / Fastify Paradigm
// Express
const router = express.Router();
router.post('/orders', authenticate, validate(createOrderSchema), async (req, res, next) => {
try {
const order = await orderService.create(req.body);
res.status(201).json(order);
} catch (err) {
next(err);
}
});
// 全局错误处理
app.use((err, req, res, next) => {
if (err instanceof NotFoundError) {
return res.status(404).json({ error: { code: 'NOT_FOUND', message: err.message } });
}
res.status(500).json({ error: { code: 'INTERNAL_ERROR', message: 'Internal Server Error' } });
});
// Fastify
fastify.post('/orders', {
schema: { body: createOrderSchema, response: { 201: orderResponseSchema } },
preHandler: [fastify.authenticate],
}, async (request, reply) => {
const order = await orderService.create(request.body);
reply.status(201).send(order);
});
Workflow
1. 读取 OpenAPI 契约
↓
2. 选定技术栈 + 分层规范
↓
3. 创建 DTO(请求/响应)
↓
4. 实现 Controller(薄)
↓
5. 实现 Service(业务逻辑)
↓
6. 实现 Repository(数据访问)
↓
7. 全局错误处理器
↓
8. 单元测试 + 集成测试
↓
9. 验证:契约一致 + 错误码统一 + 校验完备
Middleware / Interceptors (Cross-Cutting Concerns)
通用层(建议每个服务都有):
□ 认证(auth)
□ 鉴权(authorize)
□ 请求 ID 生成(trace_id)
□ 日志(access log)
□ 异常捕获(global error handler)
□ 请求体校验
□ 限流(rate limit)
□ CORS
按需层:
□ 缓存
□ 压缩
□ 安全头(helmet 风格)
□ 国际化
□ Audit log
Supporting Templates
templates/api-implementation-checklist.md— Multi-framework implementation checklist + layering verification + middleware checklist + test coverage
Quality Self-Check
□ Controller 不超过 30 行(薄)
□ 业务逻辑全部在 Service
□ DTO 与 Entity 分离
□ 入参校验完备(用框架机制)
□ 全局错误处理器统一返回格式
□ 错误码与 API 设计契约一致
□ 中间件覆盖:auth + log + trace + error + validate
□ 路由命名符合 OpenAPI 路径
□ HTTP 状态码符合语义(POST → 201 / DELETE → 204)
□ 单元测试覆盖 Service 层
□ 集成测试覆盖端到端
□ 性能验证(满足 SLA)
Common Pitfalls
- Business logic written in Controller → Hard to test, hard to reuse
- DTO and Entity shared → Change the API and you change the database
- Validation only in Controller → No protection when Service is bypassed
- Separate error handling for each endpoint → Inconsistent, missed handling
- Not using the framework's middleware mechanism → Duplicate code in every endpoint
- Controller directly calls multiple Repositories → Business logic scattered
- Global error handler swallows all exceptions → Difficult to debug
- DTO field naming inconsistent with OpenAPI → Rework during integration
- Missing request ID → Unable to trace
- Validation failures return inconsistent formats → Chaotic frontend handling
Collaboration with Other Skills
上游:
api-designer 工作流 → OpenAPI 契约
api 设计 endpoint-design / request-response → 详细规范
下游:
domain-modeling → 业务规则实现
data-access → 数据访问
auth-implementation → 中间件
testing-implementation → 测试
observability → 日志中间件
Related References
- Project root
references/backend-frameworks-2026.md— Framework comparison - Project root
references/backend-tech-stack-guide.md— Component overview