1. 为什么 Java 直连 MongoDB 写起来这么别扭如果你在 Java 项目里用过原生的 MongoDB Driver大概率经历过这种场景coll.find()拿到一个DBCursor然后手动while(cursor.hasNext())遍历再一个个getString(name)、getInteger(age)往实体里塞。字段一多代码就变成流水账换个集合又得复制粘贴一遍。这跟当年用 JDBC 裸写ResultSet的痛苦一模一样。commons-dbutils当年解决的就是这个问题——用BeanHandler、BeanListHandler把ResultSet自动映射成 JavaBean。MongoDB 这边其实也能照搬这套思路定义一个ResultSetHandlerT回调接口让调用方决定返回单个实体还是 List底层用反射 内省把DBObject的字段灌进实体。这样业务代码里只需要一行find(query, new BeanListHandler(Person.class), person)剩下的映射全自动。这篇面向的是需要统一 MongoDB 连接配置、又不想引入重型 ORM 的 Java 开发者。我会给出一套可复制的DBUtils骨架ResultSetHandler接口、BaseHandler内省基类、BeanHandler/BeanListHandler两个实现再加一个从settings.json读取连接参数的配置层。最后用 TaoToken 的模型对话能力验证一下这套骨架跑出来的结果对不对。整套代码不依赖 Spring纯 Java 官方 Driver 就能跑。2. 前置准备连接配置与 TaoToken 接入2.1 为什么连接参数要抽到 settings.json硬编码new MongoClient(127.0.0.1:27017)在本地跑没问题一旦要区分开发/测试环境就抓瞎。我的做法是把 MongoDB 的连接信息、库名、默认集合名统一放进settings.jsonJava 侧用一个轻量配置类加载。这样换环境只改 JSON不动代码。{ mongo: { host: 127.0.0.1, port: 27017, database: one, defaultCollection: person, connectTimeoutMs: 3000, socketTimeoutMs: 5000 }, taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-20250514 } }taotoken这一段是给后面验证环节用的。TaoToken 提供统一的模型调用入口兼容 Anthropic 风格的接口Java 里用HttpClient直接 POST 就行不需要额外 SDK。API Key 在控制台的 API Keys 页面生成地址是https://taotoken.net/console/api-keys。2.2 Maven 依赖只需要官方 Driver 和一个 JSON 解析库。我用 Jackson 读settings.json你也可以换成 Gson。dependencies dependency groupIdorg.mongodb/groupId artifactIdmongo-java-driver/artifactId version3.12.14/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.15.2/version /dependency /dependencies注意这里用的是 3.x 的mongo-java-driver因为DBObject、DBCursor这套 API 在 4.x 里已经被Document、FindIterable取代。如果你项目已经上了 4.x思路完全一样把类型换掉即可反射映射那段逻辑不用动。2.3 配置加载类package com.zk.config; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import java.io.InputStream; public class SettingsLoader { private static JsonNode root; static { try (InputStream in SettingsLoader.class .getClassLoader().getResourceAsStream(settings.json)) { root new ObjectMapper().readTree(in); } catch (Exception e) { throw new RuntimeException(settings.json 加载失败, e); } } public static String mongoHost() { return root.path(mongo).path(host).asText(127.0.0.1); } public static int mongoPort() { return root.path(mongo).path(port).asInt(27017); } public static String mongoDatabase() { return root.path(mongo).path(database).asText(one); } public static String defaultCollection() { return root.path(mongo).path(defaultCollection).asText(person); } }把settings.json放在src/main/resources下getResourceAsStream就能直接读到。这样连接参数和代码彻底解耦。3. 可复制配置DBUtils 骨架完整代码3.1 ResultSetHandler 回调接口这是整套设计的核心。它把「怎么处理游标」这件事交给调用方底层只负责把DBCursor递过去。package com.zk.db.handler; import com.mongodb.DBCursor; public interface ResultSetHandlerT { T handler(DBCursor cursor) throws Exception; }3.2 BaseHandler 内省基类BaseHandler不直接实现接口它只提供「把DBObject的字段灌进实体」这个公共能力。用Introspector拿到所有属性描述符再用PropertyDescriptor.getWriteMethod()拿到 setter反射调用。这里我加了一个_前缀的兼容分支因为 MongoDB 里有些字段会带下划线而 Java 实体是驼峰命名。package com.zk.db.handler; import com.mongodb.DBObject; import java.beans.BeanInfo; import java.beans.Introspector; import java.beans.PropertyDescriptor; import java.lang.reflect.Method; import java.util.Set; public class BaseHandlerT { private final ClassT clazz; public BaseHandler(ClassT clazz) { this.clazz clazz; } public void populate(T t, SetString keys, DBObject object) throws Exception { BeanInfo info Introspector.getBeanInfo(clazz); PropertyDescriptor[] pds info.getPropertyDescriptors(); for (PropertyDescriptor pd : pds) { String proName pd.getName(); if (class.equals(proName)) { continue; } Method write pd.getWriteMethod(); if (write null) { continue; } if (keys.contains(proName)) { write.invoke(t, object.get(proName)); } else if (keys.contains(_ proName)) { write.invoke(t, object.get(_ proName)); } } } }class.equals(proName)这个判断必须加。Introspector会把getClass()也当成一个属性如果不跳过反射调用setClass时会直接抛异常。3.3 BeanHandler 单实体映射package com.zk.db.handler; import com.mongodb.DBCursor; import com.mongodb.DBObject; import java.util.Set; public class BeanHandlerT extends BaseHandlerT implements ResultSetHandlerT { private final ClassT clazz; public BeanHandler(ClassT clazz) { super(clazz); this.clazz clazz; } Override public T handler(DBCursor cursor) throws Exception { if (cursor.hasNext()) { T t clazz.getDeclaredConstructor().newInstance(); DBObject object cursor.next(); SetString keys object.keySet(); populate(t, keys, object); return t; } return null; } }3.4 BeanListHandler 集合映射package com.zk.db.handler; import com.mongodb.DBCursor; import com.mongodb.DBObject; import java.util.ArrayList; import java.util.List; import java.util.Set; public class BeanListHandlerT extends BaseHandlerT implements ResultSetHandlerListT { private final ClassT clazz; public BeanListHandler(ClassT clazz) { super(clazz); this.clazz clazz; } Override public ListT handler(DBCursor cursor) throws Exception { ListT list new ArrayList(); while (cursor.hasNext()) { T t clazz.getDeclaredConstructor().newInstance(); DBObject object cursor.next(); SetString keys object.keySet(); populate(t, keys, object); list.add(t); } return list; } }3.5 MongoDb 核心封装类这个类把连接管理、查询器、回调处理串起来。注意find(DBObject, ResultSetHandler, String)这个方法——它就是整个 DBUtils 的门面调用方传一个 handler 进来底层负责把游标喂给它。package com.zk.db; import com.mongodb.DB; import com.mongodb.DBCollection; import com.mongodb.DBCursor; import com.mongodb.DBObject; import com.mongodb.MongoClient; import com.zk.config.SettingsLoader; import com.zk.db.handler.ResultSetHandler; public class MongoDb { private static MongoClient client; private static DB db; public MongoDb() { this(SettingsLoader.mongoDatabase()); } public MongoDb(String dbName) { if (client null) { client new MongoClient( SettingsLoader.mongoHost(), SettingsLoader.mongoPort() ); } db client.getDB(dbName); } public T T find(DBObject query, ResultSetHandlerT rsh, String collName) { try { DBCursor cursor find(query, null, collName); return rsh.handler(cursor); } catch (Exception e) { throw new RuntimeException(查询失败: collName, e); } } public DBCursor find(DBObject ref, DBObject keys, String collName) { DBCollection coll db.getCollection(collName); return coll.find(ref, keys); } public DBCursor find(DBObject ref, DBObject keys, int start, int limit, String collName) { return find(ref, keys, collName).limit(limit).skip(start); } public DBCollection collection(String collName) { return db.getCollection(collName); } public void close() { if (client ! null) { client.close(); client null; } } }MongoClient做成静态单例因为它是线程安全的每次new一个会浪费连接池。close()留给应用关闭时调用。3.6 实体类package com.zk.bean; public class Person { private String id; private String name; private Integer age; public String getId() { return id; } public void setId(String id) { this.id id; } public String getName() { return name; } public void setName(String name) { this.name name; } public Integer getAge() { return age; } public void setAge(Integer age) { this.age age; } Override public String toString() { return Person{id id , name name , age age }; } }字段类型要和 MongoDB 里存的一致。如果库里age存的是int实体用Integer没问题如果存的是String反射调用setAge时会抛IllegalArgumentException这个坑后面排障章节会讲。4. 验证请求连接测试与 CRUD 跑通4.1 插入测试数据先往person集合里塞几条数据方便后面验证映射。package com.zk; import com.mongodb.BasicDBObject; import com.mongodb.DBCollection; import com.mongodb.DBObject; import com.zk.db.MongoDb; public class SeedData { public static void main(String[] args) { MongoDb mongo new MongoDb(); DBCollection coll mongo.collection(person); coll.drop(); for (int i 1; i 5; i) { DBObject doc new BasicDBObject(); doc.put(name, user_ i); doc.put(age, 20 i); coll.insert(doc); } System.out.println(插入完成当前文档数: coll.count()); mongo.close(); } }运行后控制台输出插入完成当前文档数: 5。4.2 用 BeanListHandler 查询集合package com.zk; import com.mongodb.BasicDBObject; import com.mongodb.DBObject; import com.zk.bean.Person; import com.zk.db.MongoDb; import com.zk.db.handler.BeanListHandler; import java.util.List; public class QueryDemo { public static void main(String[] args) { MongoDb mongo new MongoDb(); DBObject query new BasicDBObject(age, new BasicDBObject($gte, 22)); ListPerson list mongo.find( query, new BeanListHandler(Person.class), person ); for (Person p : list) { System.out.println(p); } mongo.close(); } }预期输出Person{idnull, nameuser_2, age22} Person{idnull, nameuser_3, age23} Person{idnull, nameuser_4, age24} Person{idnull, nameuser_5, age25}id是 null因为插入时没手动设_idMongoDB 自动生成的_id是ObjectId类型而实体里id是String类型不匹配所以没灌进去。要拿到 id把实体字段改成ObjectId类型或者在populate里加类型转换。这是设计取舍不是 bug。4.3 用 BeanHandler 查单条DBObject query new BasicDBObject(name, user_3); Person p mongo.find(query, new BeanHandler(Person.class), person); System.out.println(p);输出Person{idnull, nameuser_3, age23}。4.4 用 TaoToken 验证映射结果查出来的数据对不对除了肉眼看控制台还可以让模型帮你核对字段映射是否符合预期。TaoToken 的模型对话接口兼容 Anthropic 风格Java 里用HttpClient直接调。package com.zk; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class TaoTokenVerify { public static void main(String[] args) throws Exception { ObjectMapper mapper new ObjectMapper(); ObjectNode body mapper.createObjectNode(); body.put(model, claude-sonnet-4-20250514); body.put(max_tokens, 512); ArrayNode messages body.putArray(messages); ObjectNode msg messages.addObject(); msg.put(role, user); msg.put(content, 我有一段 MongoDB 查询结果映射到 Java 实体的输出 Person{idnull, nameuser_3, age23}。 请判断 name 和 age 字段是否映射正确id 为 null 可能是什么原因); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(https://taotoken.net/api/v1/messages)) .header(Content-Type, application/json) .header(x-api-key, sk-你的Key) .header(anthropic-version, 2023-06-01) .POST(HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(body))) .build(); HttpResponseString resp HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); JsonNode result mapper.readTree(resp.body()); System.out.println(result.path(content).get(0).path(text).asText()); } }模型会告诉你name、age映射正确id为 null 是因为_id是ObjectId而实体字段是String类型不匹配导致 setter 没被调用。这种验证方式比翻文档快尤其适合字段多、类型杂的场景。如果你更习惯在网页里直接对话可以打开模型对话页面粘贴同样的内容。5. 本篇常见错排查5.1 反射调用 setter 抛 IllegalArgumentException最常见的原因是类型不匹配。MongoDB 里age存的是Integer实体里写成了Stringwrite.invoke(t, object.get(age))就会炸。解决办法有两个要么统一实体字段类型和库里的 BSON 类型要么在populate里加一层类型转换。Object value object.get(proName); if (value ! null !pd.getPropertyType().isAssignableFrom(value.getClass())) { value convert(value, pd.getPropertyType()); } write.invoke(t, value);convert方法按目标类型做Integer.parseInt、String.valueOf之类的转换。字段少的时候手动改实体更快字段多就上转换层。5.2 Introspector 把 class 当成属性前面代码里class.equals(proName)那个判断如果漏了pd.getWriteMethod()会返回 null因为Class没有setClass然后write.invoke直接 NPE。加上判断就没事。5.3 DBCursor 没关闭导致连接泄漏find方法返回DBCursor后如果调用方不遍历完也不关闭游标会一直占着连接。我的做法是在ResultSetHandler.handler里遍历完就自动耗尽游标但如果你手动拿DBCursor做分页记得在 finally 里cursor.close()。DBCursor cursor mongo.find(query, null, person); try { while (cursor.hasNext()) { // 处理 } } finally { cursor.close(); }5.4 settings.json 读不到getResourceAsStream(settings.json)返回 null通常是文件没放在src/main/resources根目录或者 Maven 没把它打进 classpath。检查target/classes下有没有这个文件。IDEA 里如果改了 resources 目录没 rebuild也会读不到。5.5 TaoToken 调用返回 401x-api-key头没带对或者 Key 已经失效。去 API Keys 页面重新生成一个确认请求头名字是x-api-key而不是Authorization。Anthropic 风格接口用的是x-api-key这点和 OpenAI 风格不一样。5.6 分页 skip 参数理解偏差find(ref, keys, start, limit, collName)里start是跳过的条数不是页码。第 2 页每页 10 条start应该是 10 而不是 2。这个参数命名容易误导我在方法注释里写清楚了。6. 接入文档与后续扩展这套骨架的核心价值在于把「查询」和「映射」解耦。ResultSetHandler接口让你可以自由扩展——想要返回Map就写个MapHandler想要返回 JSON 字符串就写个JsonHandler底层MongoDb.find完全不用改。这就是面向接口编程的好处。如果你要把这套代码用到实际项目里下一步可以做的扩展在MongoDb里加insert、update、delete的封装让 DBUtils 覆盖完整 CRUD把MongoClient换成连接池配置从settings.json读连接数参数给BaseHandler加注解支持用Field(_id)显式指定字段映射关系比_前缀匹配更灵活。TaoToken 的接入文档里有完整的接口说明和参数列表Java、Python、Node 的调用示例都有。如果你在跑这套骨架时遇到映射报错可以把异常栈和实体定义贴到模型对话里让模型帮你定位比搜索引擎翻帖子快得多。长期做 Java 后端开发的话Coding Plan 那边有包月方案适合频繁调试的场景。
Java 配 TaoToken：MongoDB DBUtils 封装骨架与 settings.json 验证
1. 为什么 Java 直连 MongoDB 写起来这么别扭如果你在 Java 项目里用过原生的 MongoDB Driver大概率经历过这种场景coll.find()拿到一个DBCursor然后手动while(cursor.hasNext())遍历再一个个getString(name)、getInteger(age)往实体里塞。字段一多代码就变成流水账换个集合又得复制粘贴一遍。这跟当年用 JDBC 裸写ResultSet的痛苦一模一样。commons-dbutils当年解决的就是这个问题——用BeanHandler、BeanListHandler把ResultSet自动映射成 JavaBean。MongoDB 这边其实也能照搬这套思路定义一个ResultSetHandlerT回调接口让调用方决定返回单个实体还是 List底层用反射 内省把DBObject的字段灌进实体。这样业务代码里只需要一行find(query, new BeanListHandler(Person.class), person)剩下的映射全自动。这篇面向的是需要统一 MongoDB 连接配置、又不想引入重型 ORM 的 Java 开发者。我会给出一套可复制的DBUtils骨架ResultSetHandler接口、BaseHandler内省基类、BeanHandler/BeanListHandler两个实现再加一个从settings.json读取连接参数的配置层。最后用 TaoToken 的模型对话能力验证一下这套骨架跑出来的结果对不对。整套代码不依赖 Spring纯 Java 官方 Driver 就能跑。2. 前置准备连接配置与 TaoToken 接入2.1 为什么连接参数要抽到 settings.json硬编码new MongoClient(127.0.0.1:27017)在本地跑没问题一旦要区分开发/测试环境就抓瞎。我的做法是把 MongoDB 的连接信息、库名、默认集合名统一放进settings.jsonJava 侧用一个轻量配置类加载。这样换环境只改 JSON不动代码。{ mongo: { host: 127.0.0.1, port: 27017, database: one, defaultCollection: person, connectTimeoutMs: 3000, socketTimeoutMs: 5000 }, taotoken: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet-4-20250514 } }taotoken这一段是给后面验证环节用的。TaoToken 提供统一的模型调用入口兼容 Anthropic 风格的接口Java 里用HttpClient直接 POST 就行不需要额外 SDK。API Key 在控制台的 API Keys 页面生成地址是https://taotoken.net/console/api-keys。2.2 Maven 依赖只需要官方 Driver 和一个 JSON 解析库。我用 Jackson 读settings.json你也可以换成 Gson。dependencies dependency groupIdorg.mongodb/groupId artifactIdmongo-java-driver/artifactId version3.12.14/version /dependency dependency groupIdcom.fasterxml.jackson.core/groupId artifactIdjackson-databind/artifactId version2.15.2/version /dependency /dependencies注意这里用的是 3.x 的mongo-java-driver因为DBObject、DBCursor这套 API 在 4.x 里已经被Document、FindIterable取代。如果你项目已经上了 4.x思路完全一样把类型换掉即可反射映射那段逻辑不用动。2.3 配置加载类package com.zk.config; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import java.io.InputStream; public class SettingsLoader { private static JsonNode root; static { try (InputStream in SettingsLoader.class .getClassLoader().getResourceAsStream(settings.json)) { root new ObjectMapper().readTree(in); } catch (Exception e) { throw new RuntimeException(settings.json 加载失败, e); } } public static String mongoHost() { return root.path(mongo).path(host).asText(127.0.0.1); } public static int mongoPort() { return root.path(mongo).path(port).asInt(27017); } public static String mongoDatabase() { return root.path(mongo).path(database).asText(one); } public static String defaultCollection() { return root.path(mongo).path(defaultCollection).asText(person); } }把settings.json放在src/main/resources下getResourceAsStream就能直接读到。这样连接参数和代码彻底解耦。3. 可复制配置DBUtils 骨架完整代码3.1 ResultSetHandler 回调接口这是整套设计的核心。它把「怎么处理游标」这件事交给调用方底层只负责把DBCursor递过去。package com.zk.db.handler; import com.mongodb.DBCursor; public interface ResultSetHandlerT { T handler(DBCursor cursor) throws Exception; }3.2 BaseHandler 内省基类BaseHandler不直接实现接口它只提供「把DBObject的字段灌进实体」这个公共能力。用Introspector拿到所有属性描述符再用PropertyDescriptor.getWriteMethod()拿到 setter反射调用。这里我加了一个_前缀的兼容分支因为 MongoDB 里有些字段会带下划线而 Java 实体是驼峰命名。package com.zk.db.handler; import com.mongodb.DBObject; import java.beans.BeanInfo; import java.beans.Introspector; import java.beans.PropertyDescriptor; import java.lang.reflect.Method; import java.util.Set; public class BaseHandlerT { private final ClassT clazz; public BaseHandler(ClassT clazz) { this.clazz clazz; } public void populate(T t, SetString keys, DBObject object) throws Exception { BeanInfo info Introspector.getBeanInfo(clazz); PropertyDescriptor[] pds info.getPropertyDescriptors(); for (PropertyDescriptor pd : pds) { String proName pd.getName(); if (class.equals(proName)) { continue; } Method write pd.getWriteMethod(); if (write null) { continue; } if (keys.contains(proName)) { write.invoke(t, object.get(proName)); } else if (keys.contains(_ proName)) { write.invoke(t, object.get(_ proName)); } } } }class.equals(proName)这个判断必须加。Introspector会把getClass()也当成一个属性如果不跳过反射调用setClass时会直接抛异常。3.3 BeanHandler 单实体映射package com.zk.db.handler; import com.mongodb.DBCursor; import com.mongodb.DBObject; import java.util.Set; public class BeanHandlerT extends BaseHandlerT implements ResultSetHandlerT { private final ClassT clazz; public BeanHandler(ClassT clazz) { super(clazz); this.clazz clazz; } Override public T handler(DBCursor cursor) throws Exception { if (cursor.hasNext()) { T t clazz.getDeclaredConstructor().newInstance(); DBObject object cursor.next(); SetString keys object.keySet(); populate(t, keys, object); return t; } return null; } }3.4 BeanListHandler 集合映射package com.zk.db.handler; import com.mongodb.DBCursor; import com.mongodb.DBObject; import java.util.ArrayList; import java.util.List; import java.util.Set; public class BeanListHandlerT extends BaseHandlerT implements ResultSetHandlerListT { private final ClassT clazz; public BeanListHandler(ClassT clazz) { super(clazz); this.clazz clazz; } Override public ListT handler(DBCursor cursor) throws Exception { ListT list new ArrayList(); while (cursor.hasNext()) { T t clazz.getDeclaredConstructor().newInstance(); DBObject object cursor.next(); SetString keys object.keySet(); populate(t, keys, object); list.add(t); } return list; } }3.5 MongoDb 核心封装类这个类把连接管理、查询器、回调处理串起来。注意find(DBObject, ResultSetHandler, String)这个方法——它就是整个 DBUtils 的门面调用方传一个 handler 进来底层负责把游标喂给它。package com.zk.db; import com.mongodb.DB; import com.mongodb.DBCollection; import com.mongodb.DBCursor; import com.mongodb.DBObject; import com.mongodb.MongoClient; import com.zk.config.SettingsLoader; import com.zk.db.handler.ResultSetHandler; public class MongoDb { private static MongoClient client; private static DB db; public MongoDb() { this(SettingsLoader.mongoDatabase()); } public MongoDb(String dbName) { if (client null) { client new MongoClient( SettingsLoader.mongoHost(), SettingsLoader.mongoPort() ); } db client.getDB(dbName); } public T T find(DBObject query, ResultSetHandlerT rsh, String collName) { try { DBCursor cursor find(query, null, collName); return rsh.handler(cursor); } catch (Exception e) { throw new RuntimeException(查询失败: collName, e); } } public DBCursor find(DBObject ref, DBObject keys, String collName) { DBCollection coll db.getCollection(collName); return coll.find(ref, keys); } public DBCursor find(DBObject ref, DBObject keys, int start, int limit, String collName) { return find(ref, keys, collName).limit(limit).skip(start); } public DBCollection collection(String collName) { return db.getCollection(collName); } public void close() { if (client ! null) { client.close(); client null; } } }MongoClient做成静态单例因为它是线程安全的每次new一个会浪费连接池。close()留给应用关闭时调用。3.6 实体类package com.zk.bean; public class Person { private String id; private String name; private Integer age; public String getId() { return id; } public void setId(String id) { this.id id; } public String getName() { return name; } public void setName(String name) { this.name name; } public Integer getAge() { return age; } public void setAge(Integer age) { this.age age; } Override public String toString() { return Person{id id , name name , age age }; } }字段类型要和 MongoDB 里存的一致。如果库里age存的是int实体用Integer没问题如果存的是String反射调用setAge时会抛IllegalArgumentException这个坑后面排障章节会讲。4. 验证请求连接测试与 CRUD 跑通4.1 插入测试数据先往person集合里塞几条数据方便后面验证映射。package com.zk; import com.mongodb.BasicDBObject; import com.mongodb.DBCollection; import com.mongodb.DBObject; import com.zk.db.MongoDb; public class SeedData { public static void main(String[] args) { MongoDb mongo new MongoDb(); DBCollection coll mongo.collection(person); coll.drop(); for (int i 1; i 5; i) { DBObject doc new BasicDBObject(); doc.put(name, user_ i); doc.put(age, 20 i); coll.insert(doc); } System.out.println(插入完成当前文档数: coll.count()); mongo.close(); } }运行后控制台输出插入完成当前文档数: 5。4.2 用 BeanListHandler 查询集合package com.zk; import com.mongodb.BasicDBObject; import com.mongodb.DBObject; import com.zk.bean.Person; import com.zk.db.MongoDb; import com.zk.db.handler.BeanListHandler; import java.util.List; public class QueryDemo { public static void main(String[] args) { MongoDb mongo new MongoDb(); DBObject query new BasicDBObject(age, new BasicDBObject($gte, 22)); ListPerson list mongo.find( query, new BeanListHandler(Person.class), person ); for (Person p : list) { System.out.println(p); } mongo.close(); } }预期输出Person{idnull, nameuser_2, age22} Person{idnull, nameuser_3, age23} Person{idnull, nameuser_4, age24} Person{idnull, nameuser_5, age25}id是 null因为插入时没手动设_idMongoDB 自动生成的_id是ObjectId类型而实体里id是String类型不匹配所以没灌进去。要拿到 id把实体字段改成ObjectId类型或者在populate里加类型转换。这是设计取舍不是 bug。4.3 用 BeanHandler 查单条DBObject query new BasicDBObject(name, user_3); Person p mongo.find(query, new BeanHandler(Person.class), person); System.out.println(p);输出Person{idnull, nameuser_3, age23}。4.4 用 TaoToken 验证映射结果查出来的数据对不对除了肉眼看控制台还可以让模型帮你核对字段映射是否符合预期。TaoToken 的模型对话接口兼容 Anthropic 风格Java 里用HttpClient直接调。package com.zk; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.databind.node.ArrayNode; import com.fasterxml.jackson.databind.node.ObjectNode; import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; public class TaoTokenVerify { public static void main(String[] args) throws Exception { ObjectMapper mapper new ObjectMapper(); ObjectNode body mapper.createObjectNode(); body.put(model, claude-sonnet-4-20250514); body.put(max_tokens, 512); ArrayNode messages body.putArray(messages); ObjectNode msg messages.addObject(); msg.put(role, user); msg.put(content, 我有一段 MongoDB 查询结果映射到 Java 实体的输出 Person{idnull, nameuser_3, age23}。 请判断 name 和 age 字段是否映射正确id 为 null 可能是什么原因); HttpRequest request HttpRequest.newBuilder() .uri(URI.create(https://taotoken.net/api/v1/messages)) .header(Content-Type, application/json) .header(x-api-key, sk-你的Key) .header(anthropic-version, 2023-06-01) .POST(HttpRequest.BodyPublishers.ofString(mapper.writeValueAsString(body))) .build(); HttpResponseString resp HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); JsonNode result mapper.readTree(resp.body()); System.out.println(result.path(content).get(0).path(text).asText()); } }模型会告诉你name、age映射正确id为 null 是因为_id是ObjectId而实体字段是String类型不匹配导致 setter 没被调用。这种验证方式比翻文档快尤其适合字段多、类型杂的场景。如果你更习惯在网页里直接对话可以打开模型对话页面粘贴同样的内容。5. 本篇常见错排查5.1 反射调用 setter 抛 IllegalArgumentException最常见的原因是类型不匹配。MongoDB 里age存的是Integer实体里写成了Stringwrite.invoke(t, object.get(age))就会炸。解决办法有两个要么统一实体字段类型和库里的 BSON 类型要么在populate里加一层类型转换。Object value object.get(proName); if (value ! null !pd.getPropertyType().isAssignableFrom(value.getClass())) { value convert(value, pd.getPropertyType()); } write.invoke(t, value);convert方法按目标类型做Integer.parseInt、String.valueOf之类的转换。字段少的时候手动改实体更快字段多就上转换层。5.2 Introspector 把 class 当成属性前面代码里class.equals(proName)那个判断如果漏了pd.getWriteMethod()会返回 null因为Class没有setClass然后write.invoke直接 NPE。加上判断就没事。5.3 DBCursor 没关闭导致连接泄漏find方法返回DBCursor后如果调用方不遍历完也不关闭游标会一直占着连接。我的做法是在ResultSetHandler.handler里遍历完就自动耗尽游标但如果你手动拿DBCursor做分页记得在 finally 里cursor.close()。DBCursor cursor mongo.find(query, null, person); try { while (cursor.hasNext()) { // 处理 } } finally { cursor.close(); }5.4 settings.json 读不到getResourceAsStream(settings.json)返回 null通常是文件没放在src/main/resources根目录或者 Maven 没把它打进 classpath。检查target/classes下有没有这个文件。IDEA 里如果改了 resources 目录没 rebuild也会读不到。5.5 TaoToken 调用返回 401x-api-key头没带对或者 Key 已经失效。去 API Keys 页面重新生成一个确认请求头名字是x-api-key而不是Authorization。Anthropic 风格接口用的是x-api-key这点和 OpenAI 风格不一样。5.6 分页 skip 参数理解偏差find(ref, keys, start, limit, collName)里start是跳过的条数不是页码。第 2 页每页 10 条start应该是 10 而不是 2。这个参数命名容易误导我在方法注释里写清楚了。6. 接入文档与后续扩展这套骨架的核心价值在于把「查询」和「映射」解耦。ResultSetHandler接口让你可以自由扩展——想要返回Map就写个MapHandler想要返回 JSON 字符串就写个JsonHandler底层MongoDb.find完全不用改。这就是面向接口编程的好处。如果你要把这套代码用到实际项目里下一步可以做的扩展在MongoDb里加insert、update、delete的封装让 DBUtils 覆盖完整 CRUD把MongoClient换成连接池配置从settings.json读连接数参数给BaseHandler加注解支持用Field(_id)显式指定字段映射关系比_前缀匹配更灵活。TaoToken 的接入文档里有完整的接口说明和参数列表Java、Python、Node 的调用示例都有。如果你在跑这套骨架时遇到映射报错可以把异常栈和实体定义贴到模型对话里让模型帮你定位比搜索引擎翻帖子快得多。长期做 Java 后端开发的话Coding Plan 那边有包月方案适合频繁调试的场景。
