怎样设计java API接口

设计 Java API 接口（这里通常指对外暴露的 RESTful / RPC 接口，也可能是内部 Java 接口设计）是一个系统工程，既要考虑功能性，也要考虑可用性、可维护性、安全性。下面我从设计原则、分层结构、命名规范、参数与返回值、异常处理、安全与版本控制等方面系统说明。

一、明确 API 的类型

先明确你设计的 API 是哪一种：

1. RESTful HTTP API（最常见，Spring Boot）
2. RPC API（Dubbo、gRPC）
3. Java 内部接口（interface）（供其他模块调用）

下面以**最主流的 RESTful Java API（Spring Boot）**为主。

二、API 设计核心原则

1. 单一职责

• 一个接口只做一件事
• 避免“万能接口”

❌ 错误示例：

POST /user  // 又注册、又登录、又改信息

✅ 正确示例：

POST /users/register
POST /users/login
PUT  /users/{id}

2. 资源导向（RESTful）

使用名词表示资源，用 HTTP 方法表达动作：

3. 统一返回格式

推荐使用统一响应对象：

public class ApiResponse<T> {
    private int code;
    private String message;
    private T data;
}

示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "name": "Tom"
  }
}

三、Java API 接口设计示例（Spring Boot）

1. Controller 层（对外暴露）

@RestController
@RequestMapping("/api/users")
public class UserController {

    @Autowired
    private UserService userService;

    @GetMapping("/{id}")
    public ApiResponse<UserDTO> getUser(@PathVariable Long id) {
        return ApiResponse.success(userService.getUserById(id));
    }

    @PostMapping
    public ApiResponse<Void> createUser(@Valid @RequestBody UserCreateRequest request) {
        userService.createUser(request);
        return ApiResponse.success();
    }
}

2. Service 层（业务逻辑）

@Service
public class UserService {

    public UserDTO getUserById(Long id) {
        // 业务逻辑
    }

    public void createUser(UserCreateRequest request) {
        // 业务逻辑
    }
}

3. DTO / Request / Response 分离

❌ 不要直接暴露 Entity

// 请求
public class UserCreateRequest {
    @NotBlank
    private String username;
}

// 返回
public class UserDTO {
    private Long id;
    private String username;
}

四、参数设计建议

1. 路径参数 vs 请求体

• 查询条件 → Query
• 创建/更新 → Body

@GetMapping("/search")
public ApiResponse<List<UserDTO>> search(
    @RequestParam String name,
    @RequestParam int page
)

2. 分页统一

{
  "page": 1,
  "size": 10,
  "total": 100,
  "records": []
}

五、异常处理

全局异常统一处理

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BusinessException.class)
    public ApiResponse<Void> handle(BusinessException e) {
        return ApiResponse.fail(e.getCode(), e.getMessage());
    }
}

六、安全性设计

1. 认证授权

• JWT / OAuth2
• Spring Security

2. 防滥用

• 限流（Gateway / Sentinel）
• 参数校验（@Valid）

3. 敏感数据

• 密码加密
• 日志脱敏

七、API 版本控制

推荐 URL 或 Header 方式：

/api/v1/users

或

Accept: application/vnd.myapi.v1+json

八、API 文档

• Swagger / OpenAPI
• 自动生成接口文档

@Operation(summary = "获取用户详情")

九、常见反模式（避免）

❌ 接口参数过多
❌ 返回结构不一致
❌ 直接用 Entity 返回
❌ 业务逻辑写在 Controller
❌ 错误码乱用

十、总结一句话

好的 Java API = 清晰的职责 + 统一的规范 + 安全的设计 + 易用的文档

如果你愿意，我可以：

• 给你一个完整 Spring Boot API 模板
• 按电商 / 用户系统 / 支付场景设计
• 对比 REST vs RPC 接口设计

你想做哪一类 API？