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 的實際輸出並排核對。這能幫助團隊具體討論「希望得到什麼」,但線上工具的切字規則不代表序列化器的實作,也不會讀取專案內的欄位標註。
- 挑選五到十個代表性名稱,包含普通單字、連續大寫、數字與重複底線。
- 先依 API 文件與資料表結構寫出預期名稱,再進行手動轉換。
- 用專案實際使用的函式庫與版本輸出同一批名稱,記錄差異。
- 決定差異應透過原始命名調整、個別標註或自訂策略處理。
- 將確認後的結果寫入測試,讓日後升級也能檢查相同契約。
這個步驟可以很小。先確認 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 與資料庫各自依契約設定。一般名稱交給統一策略,少數歷史名稱透過標註固定。
遇到縮寫、數字與重複底線時,先拿幾個真實欄位確認預期,再把結果放進測試。日後新增欄位或升級函式庫,團隊就能直接檢查契約是否改變。底線不必靠每位開發者記住,它應該由設定說清楚,再由測試守住。