把 Spring Data MongoDB 的 @Document 类连同它的嵌入类和 record 一起交给它,就能生成 controller 返回该文档时的示例 JSON。结构遵循 Spring Boot 默认的 Jackson 序列化,所以描述的是 API 响应,而不是存储在 MongoDB 里的 BSON。
对于满是嵌入列表、Map 字段和 Instant 时间戳的 MongoDB 文档,手写响应示例很繁琐,用它可以省下这些时间,还能直观看出存储格式与响应格式之间的差异。
@Document 类及其嵌入类或 record 粘贴到 Spring Data MongoDB 框中。id 和日期占位值换成真实的值。@Document(collection = "devices")
public class Device {
@Id
private String id;
private String serial;
@Field("fw")
private String firmwareVersion;
private Map<String, Double> lastReadings;
private List<Alert> alerts;
private Instant registeredAt;
}
record Alert(String level, String message, Instant raisedAt) {}{
"id": "",
"serial": "",
"firmwareVersion": "",
"lastReadings": {
"key": 0
},
"alerts": [
{
"level": "",
"message": "",
"raisedAt": "1970-01-01T00:00:00Z"
}
],
"registeredAt": "1970-01-01T00:00:00Z"
}List<Alert> 中的 Alert 是 record,所以它的组件 level、message 和 raisedAt 变成了字段。Map<String, Double> 变成 {"key": 0},Instant 是以 Z 结尾的 UTC 字符串。@Field("fw") 只改变 MongoDB 中存储的字段名,所以 JSON key 仍是 firmwareVersion。
record Alert(String level, ...))会被读取为字段。List 和 Set 变成只含一个元素的数组;Map<String, T> 变成 {"key": value}。Instant、ZonedDateTime 和 OffsetDateTime 输出 1970-01-01T00:00:00Z,LocalDateTime 则输出不带时区偏移的字符串。ObjectId 的字段会得到一个示例十六进制 ObjectId 字符串。@DBRef 关联的类如果也在输入中,会变成嵌套对象。@JsonIgnore、@JsonProperty、@JsonIgnoreProperties 以及继承字段的处理规则与 JPA 页面相同。评论列表、选项 map、历史记录数组等 MongoDB 塞进一个文档的结构,会让响应示例变得很长。粘贴这些类,每一层嵌套都会替你写出来。
通过 @Field 使用的短名称或映射到 _id 的字段,会让数据库 key 与 API key 不一致。输出展示的是 API 一侧,方便把两者放在一起对照。
@Field("...")、@Indexed、@TextIndexed 等映射注解不会改变 JSON key,因此不会体现在输出中。@Id String id 存储为 _id,但经 Jackson 输出时是 id,输出显示的正是后者。org.bson.types.ObjectId 写成带 timestamp 和 date 的对象,而不是十六进制字符串。要发送这里展示的字符串形式,请注册 ToStringSerializer 或使用 String 类型的 id。GeoJsonPoint 等 Spring Data 类型,都会变成 null。@Id 应该用 ObjectId 还是 String?用 String 时,Spring Data 在保存时会把它转换成 ObjectId,API 返回的是干净的十六进制字符串。保留 ObjectId 类型则需要为响应额外配置 Jackson。
@DBRef 字段真的会以嵌套对象返回吗?@DBRef 在读取时(lazy 模式下是首次访问时)会解析所引用的文档,所以响应中包含嵌套对象。只存储 ObjectId 或 String id 的手动引用则只返回 id。
Map<String, Object> 字段会是什么样?它的值类型未知,所以变成 {"key": null}。写进文档之前,请替换成实际存储的值。