Start by setting up a Spring Boot project using Spring Initializr with dependencies like Spring Web, Spring Data JPA, and Lombok for streamlined development. 2. Create a REST controller with @RestController and use annotations like @GetMapping, @PostMapping, @PathVariable, and @RequestBody to define and handle HTTP endpoints effectively. 3. Implement persistence using Spring Data JPA by defining an @Entity class and a repository interface extending JpaRepository, which provides built-in CRUD operations. 4. Apply validation using @Valid and bean validation annotations such as @NotBlank and @Email, and handle errors globally with @ControllerAdvice and a custom exception handler. 5. Generate API documentation automatically using Springdoc OpenAPI, accessible via swagger-ui.html, and enhance it with annotations like @Operation. 6. Follow best practices including using DTOs for API responses, maintaining separation of concerns through service and repository layers, enabling CORS and HTTPS, logging with filters or AOP, and securing the API with Spring Security for authentication and authorization. By following these steps, you can build robust, maintainable, and scalable RESTful APIs with Spring Boot efficiently.

Java API development with the Spring Framework is a go-to approach for building robust, scalable, and maintainable backend services. Spring, especially Spring Boot, simplifies the process of creating RESTful APIs by providing opinionated defaults, dependency injection, and powerful abstractions. Here’s a practical guide to building APIs effectively using Spring.

1. Set Up a Spring Boot Project

Start with Spring Initializr to generate a base project. Choose:

• Project: Maven or Gradle
• Language: Java
• Spring Boot Version: Latest stable
• Dependencies:
  • Spring Web
  • Spring Data JPA (for database access)
  • Spring Boot DevTools (for auto-reload)
  • Lombok (optional, to reduce boilerplate)

Once generated, import into your IDE. The main class will have @SpringBootApplication, which enables auto-configuration and component scanning.

2. Create a REST Controller

Use @RestController to expose HTTP endpoints. For example, a simple user API:

@RestController
@RequestMapping("/api/users")
@RequiredArgsConstructor // Lombok - avoids writing constructor
public class UserController {

    private final UserService userService;

    @GetMapping
    public List<User> getAllUsers() {
        return userService.findAll();
    }

    @GetMapping("/{id}")
    public ResponseEntity<User> getUserById(@PathVariable Long id) {
        return userService.findById(id)
                .map(ResponseEntity::ok)
                .orElse(ResponseEntity.notFound().build());
    }

    @PostMapping
    public ResponseEntity<User> createUser(@Valid @RequestBody User user) {
        User savedUser = userService.save(user);
        return ResponseEntity.ok(savedUser);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        if (userService.exists(id)) {
            userService.delete(id);
            return ResponseEntity.noContent().build();
        }
        return ResponseEntity.notFound().build();
    }
}

Key annotations:

• @GetMapping, @PostMapping, etc. — map HTTP methods
• @PathVariable — extract values from URL
• @RequestBody — bind JSON to Java object
• @Valid — trigger bean validation (e.g., with @NotBlank, @Email)

3. Use Spring Data JPA for Persistence

Define a JPA entity:

@Entity
@Table(name = "users")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @NotBlank
    private String name;

    @Email
    private String email;

    // Getters and setters (or use Lombok @Data)
}

Create a repository interface:

public interface UserRepository extends JpaRepository<User, Long> {
}

Spring Data JPA automatically provides CRUD methods. No implementation needed.

Then inject it into a service:

@Service
@Transactional
public class UserService {

    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    public List<User> findAll() {
        return userRepository.findAll();
    }

    public Optional<User> findById(Long id) {
        return userRepository.findById(id);
    }

    public User save(User user) {
        return userRepository.save(user);
    }

    public void delete(Long id) {
        userRepository.deleteById(id);
    }

    public boolean exists(Long id) {
        return userRepository.existsById(id);
    }
}

4. Handle Validation and Errors

Use bean validation annotations (javax.validation or jakarta.validation):

public class User {
    @NotBlank(message = "Name is required")
    private String name;

    @Email(message = "Email should be valid")
    private String email;
}

Handle validation errors globally:

@ControllerAdvice
public class GlobalExceptionHandler {

    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Map<String, String>> handleValidationExceptions(
            MethodArgumentNotValidException ex) {
        Map<String, String> errors = new HashMap<>();
        ex.getBindingResult().getFieldErrors().forEach(error ->
            errors.put(error.getField(), error.getDefaultMessage())
        );
        return ResponseEntity.badRequest().body(errors);
    }
}

5. Add Documentation with OpenAPI (Swagger)

Use Springdoc OpenAPI (modern replacement for Swagger):

Add dependency:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.0.2</version>
</dependency>

Access API docs at: http://localhost:8080/swagger-ui.html

You can add descriptions using annotations like @Operation, @Parameter, etc.

6. Best Practices

• Use DTOs (Data Transfer Objects): Don’t expose entities directly via API. Map to DTOs using model mappers like MapStruct or manual conversion.
• Separate concerns: Controller → Service → Repository pattern.
• Use @Valid and constraints for input validation.
• Enable HTTPS and CORS when needed:

  @Bean
  public CorsConfigurationSource corsConfigurationSource() {
      CorsConfiguration configuration = new CorsConfiguration();
      configuration.setAllowedOrigins(Arrays.asList("http://localhost:3000"));
      configuration.setAllowedMethods(Arrays.asList("GET","POST","PUT","DELETE"));
      UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
      source.registerCorsConfiguration("/**", configuration);
      return source;
  }

• Log requests/responses using filters or AOP if needed.
• Secure your API with Spring Security when adding authentication (JWT, OAuth2).

---

Building APIs with Spring is straightforward once you understand the core components. With Spring Boot, you can go from zero to a production-ready API in minutes. Focus on clean architecture, validation, and documentation to make your APIs developer-friendly and maintainable.

Basically, start small, use the right annotations, and let Spring do the heavy lifting.

The above is the detailed content of Java API Development with the Spring Framework. For more information, please follow other related articles on the PHP Chinese website!