跳到主要内容

你的 API 正在悄悄拖垮 AI 的代码质量

· 阅读需 4 分钟

AI 生成代码的质量取决于底层 API 的表达密度。对比 Python 和 Java 处理嵌套 JSON 的差异，提出 4 条 API 设计原则。

一个被忽略的事实​

同样一个需求：

从一个嵌套 JSON 里，取出 user.profile.addresses[0].city。

让 AI 写 Python，它会给你这个：

city = data["user"]["profile"]["addresses"][0]["city"]

一行。

让 AI 写 Java，它大概率会给你这个：

JsonNode root = mapper.readTree(json);
String city = null;
if (root != null) {
    JsonNode user = root.get("user");
    if (user != null) {
        JsonNode profile = user.get("profile");
        if (profile != null) {
            JsonNode addresses = profile.get("addresses");
            if (addresses != null && addresses.size() > 0) {
                JsonNode first = addresses.get(0);
                if (first != null && first.has("city")) {
                    city = first.get("city").asText();
                }
            }
        }
    }
}

17 行。

很多人把锅扔给模型：

AI 写 Java 就是不行。

但真相可能更扎心——

不是 AI 不行，是 Java 给 AI 的 API，本来就长这样。

API 的形状，决定 AI 的生成路径​

AI 写代码，不是“理解”，是“补全”。

看到 mapper.readTree(...)，它就继续 .get(...).get(...)；看到 getJSONObject(...)，它就继续 getJSONObject(...)。

API 提供什么形状，AI 就走什么轨道：

  • 低密度 API：拆开 → 声明变量 → 继续拆开。
  • 高密度 API：一个表达式，完成一段完整语义。

问题不在 AI，而在 API。

4 条规则​

1. 路径优于展开

// 展开式：6 层嵌套 + 判空
// 路径式：一行
String city = data.getString("user.profile.addresses[0].city");

路径不是字符串魔法，是把“完整意图”压缩成一个表达式。中间动作越少，AI 走偏越少。

2. 链式优于中间状态

new RequestBuilder()
    .set("name", "张三")
    .set("user.profile", profile)
    .set("user.tags", tags);

中间变量是 AI 的灾难现场：起名、类型、后续是否复用，每一个都是新的决策点。链式把这些决策收束在一个表达式里。

3. 返回意图显式，比事后转换更稳

// 模糊：拿到节点再决定怎么转
Integer age = root.get("user").get("age").asInt();

// 显式：方法名就是意图
Integer age = data.getInteger("user.age");

每多一次事后转换，AI 就多一次出错机会。

4. 稳定范式优于自由写法

如果一个项目里同时存在 readTree、readValue、parseObject、parseObj 和若干自定义封装，AI 根本不知道该用哪一个。

对人来说，API 灵活是自由。对 AI 来说，过多自由就是噪音。

最适合 AI 的 API，不一定是功能最多的，而是范式最稳的那一个。

被忽略的第四类使用者​

过去设计 API，主要考虑业务开发者、框架维护者、运行时性能。

AI 编码工具普及之后，悄悄多了一类：代码生成模型。

它不会理解你的抽象，只会顺着你的形状继续补全。

API 越啰嗦，AI 写的就越啰嗦；API 越紧凑，AI 写的就越像人写的。

回到开头那行 Python​

city = data["user"]["profile"]["addresses"][0]["city"]

Python 这一行不让人觉得是“魔法”，因为它符合人脑里“取一个嵌套字段”的最自然表达——顺着路径，一直走下去。

Python 不是语法花哨，是它的 API 形状本身就贴合这个直觉。

那么问题来了：

Java 这边，有没有同样贴合这个直觉的 API？

如果有，AI 应该会优先用它，而不是给你写 17 行判空。

如果没有，那或许该思考的，不是怎么让 AI 写得更好——

而是该让 Java 的 API，长一个 AI 能写得短的样子了。

下一篇，我们将讨论：Prompt 不是重点，团队代码规范才是 AI 编码质量的上限。