1. 为什么 jdbcType 总在 SpringBoot + Mybatis 里报错
刚接触 SpringBoot 整合 Mybatis 的时候，很多人会碰到一个很迷惑的报错：明明实体类字段和数据库列名对得上，SQL 也写得没问题，结果一运行就抛org.apache.ibatis.type.TypeException，或者提示某个 jdbcType 常量不存在。这类问题的根源，往往不是 SQL 写错了，而是 Mybatis 对 jdbcType 的枚举定义有严格限制——它只认自己那套固定清单，大小写还必须完全一致。
jdbcType 是什么？简单说，它是 Mybatis 用来告诉 JDBC 驱动「这个参数/结果列应该按哪种数据库类型处理」的标识。你在#{}里写#{name,jdbcType=VARCHAR}，Mybatis 就会去查它内部的JdbcType枚举，找到对应项再交给驱动。如果写成了varchar、Varchar，或者写了一个根本不存在的LONG，枚举查找直接失败，异常就来了。
这套枚举一共就那么多项，是固定的，不会因为你换了数据库就变多。常见的有 BIT、FLOAT、CHAR、TIMESTAMP、OTHER、UNDEFINED、TINYINT、REAL、VARCHAR、BINARY、BLOB、NVARCHAR、SMALLINT、DOUBLE、LONGVARCHAR、VARBINARY、CLOB、NCHAR、INTEGER、NUMERIC、DATE、LONGVARBINARY、BOOLEAN、NCLOB、BIGINT、DECIMAL、TIME、NULL、CURSOR。注意里面没有 LONG，Java 的long对应的是BIGINT，这一点坑过不少人。
这篇面向的是正在用 SpringBoot + Mybatis 做本地开发、并且希望顺手把 AI 接口调用通道也统一配置好的同学。我会先把 jdbcType 与 Java、MySQL 类型的映射关系完整梳理一遍，给出可直接复制的映射文件片段；然后结合 TaoToken 的统一 Key 配置，把本地开发环境里「数据库访问 + 模型接口调用」两条链路一起跑通。适合谁？适合已经能写简单 CRUD、但一遇到类型映射和接口鉴权就卡壳的初中级开发者。
我试过在同一个项目里既连 MySQL 又调模型接口，如果 Key 散落在各个配置文件里，改一次要翻好几个地方。所以下面会把 jdbcType 配置和 TaoToken 的 Key 管理放在一起讲，让本地环境一次配好、后面少折腾。
2. jdbcType 完整对照表与 Mybatis 映射文件写法
先把最核心的对照关系摆出来。下面这张表把 Java 类型、MySQL 类型、Mybatis jdbcType 三者对齐，写映射文件时直接查表即可。
| Java 类型 | MySQL 类型 | Mybatis jdbcType |
|---|---|---|
| java.lang.Byte | TINYINT | TINYINT |
| java.lang.Short | SMALLINT | SMALLINT |
| java.lang.Integer | INTEGER | INTEGER |
| java.lang.Long | BIGINT | BIGINT |
| java.lang.Float | FLOAT | FLOAT |
| java.lang.Double | DOUBLE | DOUBLE |
| java.math.BigDecimal | NUMERIC / DECIMAL | NUMERIC / DECIMAL |
| java.lang.Boolean | BIT | BIT |
| java.lang.String | VARCHAR | VARCHAR |
| java.lang.Boolean | CHAR(1) 'Y'/'N' | CHAR |
| java.util.Date | DATE | DATE |
| java.sql.Time | TIME | TIME |
| java.sql.Timestamp | TIMESTAMP | TIMESTAMP |
| java.util.Calendar | TIMESTAMP | TIMESTAMP |
| java.io.Serializable | VARBINARY / BLOB | VARBINARY / BLOB |
| java.sql.Clob | CLOB | CLOB |
| java.sql.Blob | BLOB | BLOB |
| java.lang.Class | VARCHAR | VARCHAR |
| java.util.Locale | VARCHAR | VARCHAR |
| java.util.TimeZone | VARCHAR | VARCHAR |
| java.util.Currency | VARCHAR | VARCHAR |
几个容易踩的点单独拎出来说。第一，LONG不存在，Java 的long/Long一律用BIGINT。第二，yes_no和true_false这两种布尔映射，落到 jdbcType 上都是CHAR，因为底层是 CHAR(1)。第三，date、time、timestamp三个时间类型要分清，java.util.Date通常配DATE，java.sql.Timestamp配TIMESTAMP，别混。第四，大小写严格，VARCHAR不能写成varchar。
接下来是映射文件的实际写法。假设有一张用户表t_user，字段包括id BIGINT、name VARCHAR、age INTEGER、balance DECIMAL、create_time TIMESTAMP、enabled BIT。对应的实体类字段用 Long、String、Integer、BigDecimal、Date、Boolean。XML 映射可以这样写：
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd"> <mapper namespace="com.example.demo.mapper.UserMapper"> <resultMap id="UserResultMap" type="com.example.demo.entity.User"> <id column="id" property="id" jdbcType="BIGINT"/> <result column="name" property="name" jdbcType="VARCHAR"/> <result column="age" property="age" jdbcType="INTEGER"/> <result column="balance" property="balance" jdbcType="DECIMAL"/> <result column="create_time" property="createTime" jdbcType="TIMESTAMP"/> <result column="enabled" property="enabled" jdbcType="BIT"/> </resultMap> <insert id="insertUser" parameterType="com.example.demo.entity.User"> INSERT INTO t_user (name, age, balance, create_time, enabled) VALUES ( #{name,jdbcType=VARCHAR}, #{age,jdbcType=INTEGER}, #{balance,jdbcType=DECIMAL}, #{createTime,jdbcType=TIMESTAMP}, #{enabled,jdbcType=BIT} ) </insert> <select id="selectById" resultMap="UserResultMap"> SELECT id, name, age, balance, create_time, enabled FROM t_user WHERE id = #{id,jdbcType=BIGINT} </select> </mapper>这里有个实践建议：resultMap里显式写 jdbcType 能减少驱动推断带来的歧义，尤其是BIT、DECIMAL、TIMESTAMP这类容易被误判的类型。而#{}参数里写 jdbcType，主要是解决「参数为 null 时驱动不知道类型」的问题。比如#{name}如果传了 null，某些驱动会报「无法确定参数类型」，加上jdbcType=VARCHAR就稳了。
如果你不想在每个参数上都写 jdbcType，可以在mybatis-config.xml里配置全局的jdbcTypeForNull：
<configuration> <settings> <setting name="jdbcTypeForNull" value="NULL"/> <setting name="mapUnderscoreToCamelCase" value="true"/> </settings> </configuration>jdbcTypeForNull默认是OTHER，有些数据库不认，改成NULL更通用。mapUnderscoreToCamelCase打开后，create_time能自动映射到createTime，省掉一部分 resultMap 配置。但注意，自动映射只解决列名到属性名的转换，类型层面的 jdbcType 该写还得写。
在 SpringBoot 里，这些配置通常放在application.yml：
mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.demo.entity configuration: jdbc-type-for-null: NULL map-underscore-to-camel-case: true这样一套下来，jdbcType 的映射问题基本就覆盖了。下面进入本地环境里另一条链路：模型接口调用的统一 Key 配置。
3. TaoToken 统一 Key 配置与可复制 settings 片段
本地开发时，除了数据库，很多时候还要调模型接口做辅助功能，比如代码补全、文本润色、Agent 工具调用。如果每个工具各配一套 Key，管理起来很乱。TaoToken 提供统一 Key 和 API 通道，把模型调用收敛到一个入口，配置一次就能在多个工具里复用。
先到 TaoToken 官网获取 Key。打开 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册登录后进入控制台，在 API Keys 页面创建一个新 Key。创建时建议按用途命名，比如springboot-local-dev，方便后面区分。Key 只在创建时完整显示一次，复制后妥善保存。
拿到 Key 之后，核心是三件套：Base URL、Key、Model ID。Base URL 用https://taotoken.net/api，注意这个地址不加 UTM 参数。Model ID 根据你要用的模型填，比如对话类、代码类各有对应标识，具体以控制台模型列表为准。
如果你用的是 Claude Code 这类命令行编码工具，配置通常写在settings.json里。下面是一个可复制的片段，路径按你本机实际位置调整：
{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "sk-你的TaoTokenKey", "ANTHROPIC_MODEL": "你的ModelID" } }如果你用的是 Cline 配合 MCP，配置一般落在cline_mcp_settings.json或对应工具的 settings 文件里，同样是三件套：
{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "your-mcp-server"], "env": { "BASE_URL": "https://taotoken.net/api", "API_KEY": "sk-你的TaoTokenKey", "MODEL_ID": "你的ModelID" } } } }如果你用的是 Codex，鉴权信息通常写在auth.json里：
{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的TaoTokenKey", "model": "你的ModelID" }三个文件路径不同，但字段逻辑一致：Base URL 指向https://taotoken.net/api，Key 填你创建的那串，Model ID 填控制台里对应的模型标识。把这三件套写全，工具才能正确发起请求。少任何一个，都会在调用时报鉴权失败或模型不存在。
在 SpringBoot 项目里，如果你要在代码中调用模型接口，可以把这些值放进application.yml，用配置类读取：
taotoken: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY:sk-你的Key} model-id: 你的ModelID生产环境建议用环境变量注入 Key，别硬编码在配置文件里。本地开发图方便可以先写死，但提交代码前记得换成占位符。
配置完成后，建议先做一次最小验证，确认 Key 和通道是通的。可以用 curl 直接打一个请求：
curl -X POST "https://taotoken.net/api/v1/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-你的TaoTokenKey" \ -d '{ "model": "你的ModelID", "messages": [{"role": "user", "content": "ping"}] }'如果返回里有正常的choices字段和内容，说明通道没问题。这一步能提前排掉大部分配置错误，比在工具里反复试要快。
4. 验证请求与成功结果：从 curl 到 SpringBoot 调用
配置写好了，得验证。验证分两层：先用 curl 确认 TaoToken 通道通，再在 SpringBoot 里用代码调一次，确认项目集成没问题。
先看 curl 的预期结果。上面那条命令如果成功，返回体大致长这样：
{ "id": "chatcmpl-xxxx", "object": "chat.completion", "created": 1700000000, "model": "你的ModelID", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "pong" }, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 5, "completion_tokens": 2, "total_tokens": 7 } }看到choices数组里有message.content，就说明请求成功。如果返回 401，说明 Key 不对或没带上；如果返回 404，多半是路径写错了；如果返回模型不存在，检查 Model ID 是否和控制台一致。
接着在 SpringBoot 里验证。用RestTemplate或WebClient发一个请求即可。下面用RestTemplate举例：
@RestController public class ChatController { @Value("${taotoken.base-url}") private String baseUrl; @Value("${taotoken.api-key}") private String apiKey; @Value("${taotoken.model-id}") private String modelId; private final RestTemplate restTemplate = new RestTemplate(); @PostMapping("/chat") public String chat(@RequestBody String userInput) { HttpHeaders headers = new HttpHeaders(); headers.setContentType(MediaType.APPLICATION_JSON); headers.setBearerAuth(apiKey); Map<String, Object> body = new HashMap<>(); body.put("model", modelId); body.put("messages", List.of(Map.of("role", "user", "content", userInput))); HttpEntity<Map<String, Object>> entity = new HttpEntity<>(body, headers); ResponseEntity<String> response = restTemplate.postForEntity( baseUrl + "/v1/chat/completions", entity, String.class); return response.getBody(); } }启动项目后，用 Postman 或 curl 打一下/chat接口：
curl -X POST "http://localhost:8080/chat" \ -H "Content-Type: application/json" \ -d '"你好"'返回里能看到模型回复，就说明 SpringBoot 项目已经成功接入了 TaoToken 通道。这一步和前面的 jdbcType 配置是两条独立链路，但都在同一个本地环境里，配好之后开发效率会明显提升。
顺便验证一下数据库那条链路。写一个简单的测试，插入一条用户数据再查出来：
@SpringBootTest class UserMapperTest { @Autowired private UserMapper userMapper; @Test void testInsertAndSelect() { User user = new User(); user.setName("测试用户"); user.setAge(25); user.setBalance(new BigDecimal("100.50")); user.setCreateTime(new Date()); user.setEnabled(true); userMapper.insertUser(user); User found = userMapper.selectById(user.getId()); assertNotNull(found); assertEquals("测试用户", found.getName()); } }如果这个测试通过，说明 jdbcType 映射和 Mybatis 配置都没问题。两条链路都验证过，本地开发环境就算搭好了。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
配置过程中最容易撞上的几类报错，这里逐个对照排查。
401 Unauthorized。这个最常见，基本是 Key 的问题。先确认请求头里Authorization: Bearer sk-xxx格式对不对，Bearer 和 Key 之间有一个空格。再确认 Key 有没有复制完整，有没有多出空格或换行。如果 Key 是从控制台复制的，注意别把前后空白带进去。还有一种情况是 Key 被删了或过期了，去控制台重新生成一个。
local proxy failed。这个报错通常出现在工具通过本地代理转发请求时。先检查 Base URL 是不是写成了https://taotoken.net/api，有没有多写或少写路径。再检查本地网络能不能正常访问这个地址，可以用curl -I https://taotoken.net/api看返回。如果工具配置里同时有代理设置和 Base URL，确认两者不冲突。有些工具会读系统代理，如果系统代理指向了不可用的地址，也会报这个。
reading choices 相关报错。比如Cannot read property 'choices' of undefined或reading 'choices'。这通常意味着返回体结构不对，代码里按response.choices[0]取值时，response是 undefined 或没有 choices 字段。原因可能是请求根本没成功，返回的是错误信息而不是正常响应。先打印完整返回体看看，如果是错误码，按错误码排查；如果返回体是字符串而不是 JSON，检查Content-Type和解析方式。
OAuth 相关报错。如果工具走的是 OAuth 流程而不是直接填 Key，报错可能提示 token 无效或授权失败。这种情况下，确认你用的是 API Key 模式而不是 OAuth 模式。TaoToken 的接入以 Key 为主，配置里填 Base URL + Key + Model ID 三件套即可，不需要走 OAuth 授权流程。如果工具默认走 OAuth，去设置里切换成 API Key 模式。
再补充几个 jdbcType 相关的报错。TypeException: Could not set parameters，多半是#{}里 jdbcType 写错或没写，参数为 null 时驱动无法推断类型。No enum constant org.apache.ibatis.type.JdbcType.XXX，说明你写的 jdbcType 不在枚举清单里，或者大小写不对，比如写了LONG、varchar。Invalid column type，检查 resultMap 里的 jdbcType 和数据库实际列类型是否匹配。
排查顺序建议：先看完整报错信息，定位是鉴权问题还是类型问题；鉴权问题查 Key 和三件套，类型问题查 jdbcType 枚举和大小写。把报错原文贴出来对照，比盲目改配置快得多。
6. 把 Key 和类型配置收进一个本地环境
到这里，两条链路都跑通了。jdbcType 这边，核心就是记住那套固定枚举、严格大小写、没有 LONG 用 BIGINT，映射文件里该显式写的地方别偷懒。TaoToken 这边，核心是三件套 Base URL、Key、Model ID，配置一次就能在多个工具里复用。
如果你后面要长期做编码和 Agent 相关开发，可以考虑用 Coding Plan，把模型调用额度集中管理，省得每次单独配。需要看模型能力或做对话验证，直接去模型对话页面试。Key 的管理和创建在 API Keys 页面，接入细节看接入文档。
把本地环境的 Key 统一收口之后，改配置只需要动一个地方，项目里其他部分不用跟着改。这是我在多个项目里切换后觉得最省事的一种做法。数据库类型映射和接口鉴权这两件事，看起来不相关，但都是本地开发环境的基础设施，一次配好，后面写业务代码时就能少分心。
