Spring Boot客户CRUD REST API请求/响应体结构设计咨询

一、POST /customer 请求体设计 #

由于id由数据库自动生成，且customer_type是不可变的 lookup表，客户端仅需传递客户类型的标识（type），无需携带描述或id。请求体只需包含创建客户的必要字段：

{
  "firstName": "John",
  "lastName": "Doe",
  "customerType": {
    "type": "P"
  }
}

设计逻辑：

• 无需传递id：数据库自增生成，服务端插入时自动处理。
• customerType仅传type：描述信息由服务端根据type从customer_type表查询填充，避免客户端传递冗余或可能错误的描述数据，同时契合lookup表的不可变特性。

请求体与GET响应体不一致是合理的：请求体是客户端提交的输入数据（仅需必要字段），响应体是服务端返回的完整资源表示（包含关联的描述信息），两者职责不同，无需强制一致。

二、PUT /customer/{id} 请求体设计 #

PUT用于更新指定ID的客户资源，路径中的{id}已经明确了目标资源，因此请求体中不需要传递id。请求体仅需包含需要更新的字段：

{
  "firstName": "John Updated",
  "lastName": "Doe Updated",
  "customerType": {
    "type": "S"
  }
}

关于请求体中传递id的处理 #

如果客户端在请求体中额外传递了id，服务端必须做校验：

• 若请求体中的id与路径{id}不一致，直接返回400 Bad Request错误，并提示"请求体ID与路径ID不匹配"。
• 若一致，可忽略该字段，以路径ID为准进行更新操作。

设计逻辑：

• 路径ID是RESTful API中标识资源的权威依据，请求体中的ID属于冗余或可能的错误输入，必须以路径ID优先。
• 严格校验避免客户端误操作更新错误的资源，保证数据一致性。

三、Spring Data JPA实现建议 #

为了适配输入输出的差异，建议使用DTO分离输入和输出：

1. CreateCustomerDTO/UpdateCustomerDTO：对应POST/PUT的请求体，只包含必要字段。
2. CustomerResponseDTO：对应GET的响应体，包含完整的客户信息及关联的客户类型描述。

实体类关联示例：

@Entity
@Table(name = "customer")
public class Customer {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String firstName;
    private String lastName;
    
    @ManyToOne(fetch = FetchType.EAGER)
    @JoinColumn(name = "type")
    private CustomerType customerType;
    // getter/setter
}

@Entity
@Table(name = "customer_type")
public class CustomerType {
    @Id
    private String type;
    private String description;
    // getter/setter
}

在服务层，将DTO转换为实体时，根据customerType.type从数据库查询对应的CustomerType实体，关联到Customer中即可。

内容的提问来源于stack exchange，提问作者TopoDiFogna