SuperAPI AI Directory

api-implementation

Coding & development

View repository

Updated 10-16 09:30

About this skill

API Implementation

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           → 业务实体
  1. Controllers thin as paper Controller does not contain business logic

  2. DTO and Entity separated Use DTOs to receive input / return responses ORM entities are not exposed directly to the outside

  3. Validation at the boundary Input validation at the Controller layer (using framework mechanisms) Business rule validation at the Service layer

  4. Unified error handling Global error handler + exception mapping

  5. 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

  1. Business logic written in Controller → Hard to test, hard to reuse
  2. DTO and Entity shared → Change the API and you change the database
  3. Validation only in Controller → No protection when Service is bypassed
  4. Separate error handling for each endpoint → Inconsistent, missed handling
  5. Not using the framework's middleware mechanism → Duplicate code in every endpoint
  6. Controller directly calls multiple Repositories → Business logic scattered
  7. Global error handler swallows all exceptions → Difficult to debug
  8. DTO field naming inconsistent with OpenAPI → Rework during integration
  9. Missing request ID → Unable to trace
  10. 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