API设计最佳实践

概述

API设计是软件开发中的重要环节。本教程介绍RESTful API和GraphQL的设计最佳实践。

1. RESTful API设计

@RestController
@RequestMapping("/api/v1/users")
public class UserController {
    // 资源命名规范
    // GET    /api/v1/users          - 获取用户列表
    // GET    /api/v1/users/{id}     - 获取单个用户
    // POST   /api/v1/users          - 创建用户
    // PUT    /api/v1/users/{id}     - 更新用户
    // DELETE /api/v1/users/{id}     - 删除用户
    
    @GetMapping
    public ResponseEntity<List<UserDto>> getUsers(
            @RequestParam(defaultValue = "0") int page,
            @RequestParam(defaultValue = "10") int size) {
        return ResponseEntity.ok(userService.findAll(page, size));
    }
    
    @GetMapping("/{id}")
    public ResponseEntity<UserDto> getUser(@PathVariable Long id) {
        return userService.findById(id)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }
    
    @PostMapping
    public ResponseEntity<UserDto> createUser(@Valid @RequestBody CreateUserRequest request) {
        UserDto created = userService.create(request);
        return ResponseEntity.ok(created);
    }
    
    @PutMapping("/{id}")
    public ResponseEntity<UserDto> updateUser(
            @PathVariable Long id,
            @Valid @RequestBody UpdateUserRequest request) {
        return userService.update(id, request)
            .map(ResponseEntity::ok)
            .orElse(ResponseEntity.notFound().build());
    }
    
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        if (userService.delete(id)) {
            return ResponseEntity.noContent().build();
        }
        return ResponseEntity.notFound().build();
    }
}

2. GraphQL

import graphql.schema.DataFetcher;
import graphql.schema.idl.RuntimeWiring;
import graphql.schema.idl.SchemaGenerator;
import graphql.schema.idl.SchemaParser;
import graphql.schema.idl.TypeDefinitionRegistry;

@Controller
public class GraphQLController {
    @PostMapping("/graphql")
    public ResponseEntity<Map<String, Object>> graphql(@RequestBody Map<String, Object> request) {
        String query = (String) request.get("query");
        Map<String, Object> variables = (Map<String, Object>) request.get("variables");
        
        // 执行GraphQL查询
        ExecutionResult result = graphQL.execute(query, variables);
        
        return ResponseEntity.ok(result.toSpecification());
    }
}

# schema.graphql
type Query {
    user(id: ID!): User
    users(page: Int, size: Int): [User]
}

type User {
    id: ID!
    name: String!
    email: String!
    age: Int
}

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

3. 实际应用示例

API版本控制

// URL版本控制
@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 {
    // v1版本实现
}

@RestController
@RequestMapping("/api/v2/users")
public class UserControllerV2 {
    // v2版本实现
}

// Header版本控制
@RestController
@RequestMapping("/api/users")
public class UserController {
    @GetMapping(produces = "application/vnd.myapp.v1+json")
    public ResponseEntity<List<UserDto>> getUsersV1() {
        // v1版本实现
    }
    
    @GetMapping(produces = "application/vnd.myapp.v2+json")
    public ResponseEntity<List<UserDto>> getUsersV2() {
        // v2版本实现
    }
}

API文档

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户CRUD操作")
public class UserController {
    @Operation(
        summary = "获取用户列表",
        description = "分页获取用户列表",
        responses = {
            @ApiResponse(responseCode = "200", description = "成功"),
            @ApiResponse(responseCode = "500", description = "服务器错误")
        }
    )
    @GetMapping
    public ResponseEntity<List<UserDto>> getUsers(
            @Parameter(description = "页码") @RequestParam(defaultValue = "0") int page,
            @Parameter(description = "每页大小") @RequestParam(defaultValue = "10") int size) {
        return ResponseEntity.ok(userService.findAll(page, size));
    }
}

4. 最佳实践

1. 版本控制：使用URL或Header进行版本控制
2. 错误处理：统一错误响应格式
3. 文档化：使用Swagger/OpenAPI生成文档
4. 安全性：使用JWT或OAuth2进行认证
5. 性能优化：使用分页、缓存等技术

总结

API设计是软件开发中的重要环节。掌握RESTful API和GraphQL的设计最佳实践，可以构建高质量的API接口。