20 November 2026

Java 與 .NET 串接資料庫時的 snake_case 命名轉換,從 JSON 欄位映射到縮寫與數字混用的邊界處理

Java 與 .NET 串接資料庫時的 snake_case 命名轉換,從 JSON 欄位映射到縮寫與數字混用的邊界處理

資料庫明明有 user_name,API 卻回傳 userName。換成 C# 後,物件裡又寫成 UserName。三個名稱指向同一份資料,程式卻不一定知道。最讓人頭痛的情況,是一般欄位都正常,只有 URLValue 或 version2Code 在部署後突然對不上。

這類問題不只是字串格式。Java 與 .NET 各有慣用命名,JSON 序列化器與資料庫映射工具也各自管理不同邊界。先把責任分清楚,再處理縮寫、數字與底線,程式會比到處補字串取代更容易維護。

先掌握這五個命名重點

  • JSON 名稱與資料庫欄位名稱,必須分別設定。
  • 一般欄位適合統一策略,歷史例外適合明確映射。
  • 縮寫與數字沒有唯一切法,先寫下預期結果。
  • 手動轉換用來核對契約,正式行為由程式設定與測試固定。
  • 轉換可能產生命名碰撞,也不保證能還原原名。

同一個使用者名稱,為何會出現三種寫法

Java 的一般欄位與屬性常用 camelCase,例如 userName。C# 公開屬性通常使用 PascalCase,例如 UserName。資料庫團隊則可能採用 snake_case,將欄位命名為 user_name。

這三種寫法沒有誰比較正確。問題在於,資料跨過邊界時,誰負責把名稱對起來。

資料庫欄位:user_name
Java 屬性:userName
C# 屬性:UserName
JSON 欄位:user_name

上面的安排很常見,但不能只設定一次就期待全部生效。JSON 序列化設定控制的是物件與 JSON 之間的名稱。ORM 設定或 SQL 查詢控制的,才是物件與資料庫欄位的對應。

因此,API 能輸出 user_name,不代表 ORM 已經知道要讀取同名資料庫欄位。反過來,查詢成功,也不代表回傳 JSON 的命名符合前端預期。除錯時先確認出問題的是哪一道邊界,通常能省掉不少時間。

Java 先把 JSON 與資料庫映射分開設定

以下使用 Jackson 2.x 的套件與 API。假設 Java 物件保留 camelCase,對外 JSON 統一採用 snake_case,可以在建立共用的 ObjectMapper 時指定命名策略。

import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.PropertyNamingStrategies;

public class JsonExample {
    public static class UserDto {
        public String userName;
        public String accountStatus;
    }

    public static void main(String[] args) throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        mapper.setPropertyNamingStrategy(
            PropertyNamingStrategies.SNAKE_CASE
        );

        UserDto user = new UserDto();
        user.userName = "小林";
        user.accountStatus = "active";

        System.out.println(mapper.writeValueAsString(user));
    }
}

輸出的 JSON 會包含 user_name 與 account_status。讀入相同結構的 JSON 時,這個策略也會參與屬性名稱的對應。範例使用公開欄位讓重點清楚,正式專案可以依原本架構改用存取方法或其他 DTO 寫法。

如果只有一個欄位需要保留特殊名稱,就不必為它重寫整套策略。以下例子把外部契約明確固定為 external_id。

import com.fasterxml.jackson.annotation.JsonProperty;

public class ExternalUserDto {
    @JsonProperty("external_id")
    public String externalId;
}

資料庫映射則另行處理。以 Jakarta Persistence 為例,@Column 指定的是資料庫欄位,並不設定 JSON。

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.Id;

@Entity
public class UserAccount {
    @Id
    private Long id;

    @Column(name = "user_name")
    private String userName;
}

專案也可能透過 ORM 命名策略推導欄位名稱。這時應確認實際啟用的設定,而不是只看 Java 類別猜測。對既有資料表而言,明確標註少數特殊欄位,往往比修改全域策略更容易評估影響。

.NET 讓 PascalCase 屬性輸出為 snake_case

在 .NET 8 及後續版本中,System.Text.Json 提供 JsonNamingPolicy.SnakeCaseLower。建立序列化選項後,便能讓 C# 的 PascalCase 屬性以小寫底線格式輸出。

using System.Text.Json;

var options = new JsonSerializerOptions
{
    PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower
};

var user = new UserDto
{
    UserName = "小林",
    AccountStatus = "active"
};

string json = JsonSerializer.Serialize(user, options);
Console.WriteLine(json);

public sealed class UserDto
{
    public string UserName { get; set; } = "";
    public string AccountStatus { get; set; } = "";
}

這裡使用的是屬性。若把類別成員改寫成一般欄位,就需要另外留意 System.Text.Json 的欄位納入設定,不能直接假設行為相同。

處理單一例外時,可使用 JsonPropertyName。它會優先決定該屬性的 JSON 名稱,適合固定外部系統留下的特殊契約。

using System.Text.Json.Serialization;

public sealed class ExternalUserDto
{
    [JsonPropertyName("external_id")]
    public string ExternalId { get; set; } = "";
}

如果使用 Entity Framework Core,資料庫欄位可以透過模型設定指定。以下程式放在資料庫內容類別的 OnModelCreating 中。

modelBuilder.Entity<UserAccount>()
    .Property(user => user.UserName)
    .HasColumnName("user_name");

不要把這段設定與 JSON 選項混在一起理解。它們恰好可以使用相同名稱,但各自處理不同工作。若使用 ASP.NET Core,也要把命名選項接到實際處理請求的管線。控制器與 Minimal API 的設定入口不同,單獨建立一份選項物件,不會自動改變所有端點。

先挑少量欄位,把預期名稱確認清楚

在正式套用全域策略之前,先挑幾個能代表專案習慣的名稱。不要只挑 userName。也加入縮寫、版本號,以及既有資料表中不太規則的底線名稱。

討論命名時,可以先用 snake case converter 手動整理候選名稱,再把結果與 Java、.NET 的實際輸出並排核對。這能幫助團隊具體討論「希望得到什麼」,但線上工具的切字規則不代表序列化器的實作,也不會讀取專案內的欄位標註。

  1. 挑選五到十個代表性名稱,包含普通單字、連續大寫、數字與重複底線。
  2. 先依 API 文件與資料表結構寫出預期名稱,再進行手動轉換。
  3. 用專案實際使用的函式庫與版本輸出同一批名稱,記錄差異。
  4. 決定差異應透過原始命名調整、個別標註或自訂策略處理。
  5. 將確認後的結果寫入測試,讓日後升級也能檢查相同契約。

這個步驟可以很小。先確認 userName、URLValue、version2Code 與 user__name,就比直接把數百個欄位批次轉換更容易發現分歧。拿去線上工具比對的內容只需要欄位名稱,不必附上真實資料值。

連續大寫縮寫,是兩端最容易分歧的地方

最直覺的轉換方式,是在每個大寫字母前加底線。但這樣會把 URLValue 拆成 u_r_l_value。多數團隊其實希望 URL 被視為完整縮寫,得到 url_value。

問題是,不同函式庫對縮寫結尾的判斷不一定相同。Jackson 2.x 的 snake_case 策略會把連續大寫視為一段,因此直接轉換 URLValue 時,會得到 urlvalue。System.Text.Json 的對應策略則會辨識縮寫與後續單字的邊界,得到 url_value。

這個差異值得用專案版本親自驗證。以下程式測試的是原始名稱轉換,不包含 JavaBean 存取方法辨識等其他步驟。

var strategy =
    new PropertyNamingStrategies.SnakeCaseStrategy();

System.out.println(strategy.translate("URLValue"));
System.out.println(strategy.translate("urlValue"));
Console.WriteLine(
    JsonNamingPolicy.SnakeCaseLower.ConvertName("URLValue"));

Console.WriteLine(
    JsonNamingPolicy.SnakeCaseLower.ConvertName("UrlValue"));

新欄位可以採用較一致的原始命名,例如 Java 使用 urlValue,C# 使用 UrlValue。既有欄位若不能調整,就以明確標註固定外部名稱。對跨語言 API 而言,真正需要一致的是傳輸契約,內部識別字仍可遵循各語言慣例。

數字應該黏在哪裡,要由資料語意決定

version2Code 應該轉成 version2_code,還是 version_2_code?兩者都有人使用。數字可能是版本號、規格名稱,也可能是欄位序號,單靠大小寫無法判斷。

例如 addressLine1 通常適合對應 address_line1。但如果既有資料表使用 address_line_1,應以資料表契約為準。這時明確指定映射,比要求通用演算法理解每個欄位更直接。

同樣地,OAuth2Token 同時包含縮寫與數字,更不適合靠直覺推算。不要因為某個名稱看起來像三個單字,就認定所有序列化器都會切成相同片段。先確定預期結果,再測試目前版本的實際輸出。

若團隊決定在字母與數字之間一律插入底線,也應寫清楚適用範圍。這項規則可能改變 ipv6、sha256 等慣用寫法。命名政策越具體,後續新增欄位時越少爭論。

重複底線不是可以隨手清理的雜訊

看到 user__name,很容易想把它整理成 user_name。但如果資料表真的存在前者,或外部 JSON 早已採用這個名稱,自動清理就等於修改契約。

另一個風險是碰撞。假設輸入同時有 userName 與 user_name,一般轉換就可能讓兩者落到同一個目標名稱。如果又把重複底線壓縮,user__name 也可能加入同一組。

這時不能靠「後面的值覆蓋前面的值」解決。應在建立欄位映射時就偵測重複,讓開發者看見是哪兩個原始名稱產生衝突。序列化器面對重複名稱時的行為也可能不同,不應把它當成資料整併機制。

對既有系統,保留原名並明確映射通常比較可控。對新介面,則可以在設計階段拒絕前後底線或連續底線。兩種做法的差別在於是否已有相容性需求,不能只憑外觀決定。

需要自訂轉換時,先限制規則的用途

若專案真的需要統一的文字正規化工具,可以先處理縮寫邊界,再處理小寫或數字接大寫的邊界。以下 Java 範例限於 ASCII 識別字,保留數字與前方單字相連,並明確選擇壓縮重複底線。

import java.util.Locale;

public static String normalizeIdentifier(String input) {
    if (input == null || input.isEmpty()) {
        return input;
    }

    return input
        .replaceAll("([A-Z]+)([A-Z][a-z])", "$1_$2")
        .replaceAll("([a-z0-9])([A-Z])", "$1_$2")
        .replaceAll("_+", "_")
        .toLowerCase(Locale.ROOT);
}

在這套規則中,URLValue 會成為 url_value,version2Code 會成為 version2_code,user__name 會成為 user_name。這些結果是刻意選擇的政策,不是所有 snake_case 工具共同遵循的標準。

這段函式也不會自行改變 Jackson、System.Text.Json 或 ORM 的行為。若要接入正式流程,仍須透過對應擴充點設定,並補上碰撞檢查。既有框架策略已經符合需求時,直接使用框架通常更省事。

如果識別字可能包含中文或其他 Unicode 字元,也要重新界定允許的字元範圍。不要把只比對英文字母的正規表示式,當成涵蓋所有文字的命名工具。

測試要固定外部契約,也要走過真正的資料路徑

單純測試「輸出有底線」不夠。測試應明確指出哪個欄位必須出現,以及它的值是否正確。下面的 Java 範例使用 JUnit 5,確認常見欄位與特殊縮寫都符合契約。

import com.fasterxml.jackson.annotation.JsonProperty;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.PropertyNamingStrategies;
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class UserJsonTest {
    public static class Payload {
        public String userName = "小林";

        @JsonProperty("url_value")
        public String urlValue = "sample";
    }

    @Test
    void keepsExpectedJsonNames() throws Exception {
        ObjectMapper mapper = new ObjectMapper();
        mapper.setPropertyNamingStrategy(
            PropertyNamingStrategies.SNAKE_CASE
        );

        String json = mapper.writeValueAsString(new Payload());
        var tree = mapper.readTree(json);

        assertEquals("小林", tree.get("user_name").asText());
        assertEquals("sample", tree.get("url_value").asText());
        assertFalse(tree.has("userName"));

        Payload restored = mapper.readValue(json, Payload.class);
        assertEquals("小林", restored.userName);
    }
}

.NET 端也可以使用 xUnit,直接檢查 JSON 屬性。不要比較整段 JSON 的排列順序,因為欄位順序通常不是這份契約的重點。

using System.Text.Json;
using Xunit;

public sealed class UserJsonTests
{
    [Fact]
    public void KeepsExpectedJsonNames()
    {
        var options = new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower
        };

        var source = new UserDto { UserName = "小林" };
        string json = JsonSerializer.Serialize(source, options);

        using var document = JsonDocument.Parse(json);
        var root = document.RootElement;

        Assert.Equal(
            "小林",
            root.GetProperty("user_name").GetString());

        Assert.False(root.TryGetProperty("UserName", out _));

        var restored = JsonSerializer.Deserialize<UserDto>(
            json, options);

        Assert.NotNull(restored);
        Assert.Equal("小林", restored!.UserName);
    }
}

除了往返測試,也要讀入一份獨立撰寫、已確認正確的 JSON。否則,同一套錯誤設定可能同時負責寫出與讀回,測試仍然通過,外部客戶端卻無法使用。

資料庫端則安排小型整合測試。寫入一筆資料,再透過正式查詢路徑讀回,確認實際欄位映射。JSON 測試無法代替這一步。若使用 JDBC 或手寫 SQL,也應明確指定欄位讀取名稱,避免依賴未確認的自動轉換。

另外,字典鍵與一般物件屬性也要分別考慮。System.Text.Json 的 DictionaryKeyPolicy 是獨立設定,不能從 PropertyNamingPolicy 推論字典鍵一定會同步轉換。屬性名稱策略同樣不會自動改寫字串值中的識別字。

讓底線成為可驗證的約定

穩定的命名映射,靠的是每個邊界都有清楚的責任。Java 保留團隊熟悉的 camelCase,C# 使用 PascalCase,JSON 與資料庫各自依契約設定。一般名稱交給統一策略,少數歷史名稱透過標註固定。

遇到縮寫、數字與重複底線時,先拿幾個真實欄位確認預期,再把結果放進測試。日後新增欄位或升級函式庫,團隊就能直接檢查契約是否改變。底線不必靠每位開發者記住,它應該由設定說清楚,再由測試守住。

Related Post