Controller Layer Design

In Spring Boot Web development, the Controller layer—typically referring to classes annotated with @RestController or @Controller—serves as the critical hub connecting frontend requests with backend business logic. It is responsible for receiving HTTP requests, parsing parameters, invoking the Service layer to handle business operations, and encapsulating results before returning them in a standard format to clients. A well-designed Controller layer not only enhances code maintainability but also significantly reduces system coupling, ensuring clear responsibilities within the Web tier. This article delves into design principles of the Controller layer, common patterns, and practical examples.
One core design philosophy of Spring MVC is "layered architecture." The Controller layer should not contain complex business logic; its sole responsibility is to act as the entry point for requests and the exit point for responses. Placing core algorithms or data validation logic directly within the Controller leads to code that is difficult to test, hard to maintain, and prone to performance bottlenecks. Therefore, the primary principle when designing a Controller is Separation of Concerns: it should be responsible only for "what" needs to happen (What), not "how" it happens (How).

Reception and Parsing: Automatically extract request parameters using annotations such as @RequestParam, @PathVariable, or @RequestBody.
Invoking Business Layer: Obtain Service interface instances via Dependency Injection (DI) and delegate specific business processing to them.
Result Encapsulation: Convert data returned by the Service into a unified response structure (such as DTOs or VO), setting appropriate HTTP status codes and Content-Type headers.

Unified Response Format Design

To simplify frontend interaction and facilitate error handling, it is recommended to establish a unified response wrapper class within the Controller. This pattern requires that regardless of success or failure, the HTTP response body follows the same JSON structure, typically containing three fields: code, message, and data.

@Data
public class Result<T> {
    private Integer code;
    private String message;
    private T data;

    public static <T> Result<T> success(T data) {
        Result<T> result = new Result<>();
        result.setCode(200);
        result.setMessage("Operation successful"); // Translated from "操作成功"
        result.setData(data);
        return result;
    }

    public static <T> Result<T> error(String message, Integer code) {
        Result<T> result = new Result<>();
        result.setCode(code);
        result.setMessage(message);
        result.setData(null);
        return result;
    }
}

By adopting this approach, frontend developers do not need to perform extensive try-catch judgments in the JS layer; they simply decide subsequent actions based on the code field. Furthermore, uncaught exceptions can be intercepted by a global exception handler (@ControllerAdvice) to uniformly return error codes and friendly message prompts.

Parameter Validation and Security

In modern Web applications, the validity of input data directly impacts system security and stability. Spring Boot provides powerful Bean Validation mechanisms (based on JSR-303/380), allowing validation rules to be defined directly on parameter annotations in Controllers.

public class UserDTO {
    @NotBlank(message = "Username cannot be empty") // Translated from "用户名不能为空"
    private String username;
    
    @Pattern(regexp = "^[a-zA-Z0-9]{6,16}$", message = "Incorrect password format") // Translated from "密码格式不正确"
    private String password;
}

When parameters fail to meet validation rules, Spring automatically returns a 400 Bad Request status code along with specific error information. Additionally, for interfaces involving sensitive data or user identity, the Controller layer must work in conjunction with Spring Security to implement access control, ensuring that only authorized users can access specific resources.

Asynchronous Processing and Performance Optimization

In high-concurrency scenarios, synchronous blocking processing within Controllers may lead to request timeouts. For time-consuming tasks (such as sending emails, generating reports, or calling third-party APIs), the Controller layer should introduce asynchronous processing capabilities. Spring Boot natively supports asynchronous execution based on thread pools; combining this with the @Async annotation enables non-blocking responses.

@Service
@EnableAsync
public class AsyncService {
    @Async
    public void sendReportEmail(String userId) {
        // Time-consuming operation
        System.out.println("Generating report and sending email..."); // Translated comment from "正在生成报告并发送邮件..."
        Thread.sleep(5000);
        System.out.println("Email sent successfully"); // Translated comment from "邮件发送完成"
    }
}

@RestController
public class UserController {
    @Autowired
    private AsyncService asyncService;

    @GetMapping("/report/{userId}")
    public Result<Void> generateReport(@PathVariable String userId) {
        // Return success immediately without waiting for email completion
        return Result.success(null); 
    }
}

This design pattern makes users perceive that their request has been submitted, thereby improving the user experience. Of course, if notification of task completion is required, it can be further decoupled by combining message queues (such as RabbitMQ) or background scheduled tasks.

Summary

The quality of Controller layer design directly reflects the architectural maturity of a Spring Boot application. By adhering to single responsibility, unified response formats, strict parameter validation, and reasonably utilizing asynchronous mechanisms, developers can build robust, efficient, and easily extensible Web applications. In actual projects, it is recommended to combine Swagger/OpenAPI specifications for interface documentation descriptions, making Controller layer logic more transparent and standardized.