Java 與 JSON 的交接
若要將 Java properties 轉換為 JSON，請依照 java.util.Properties.load(Reader) 風格的規則解析文字，並將每個值輸出為 JSON 字串。
Properties 轉 JSON 轉換器可將已經以 Unicode 字元形式存在的文字進行轉換。貼上 properties，在本機進行轉換，然後複製產生的格式化 JSON 物件。這個頁面不會上傳檔案、連線至 Java 程序或評估預留位置，因此應將它視為格式轉換步驟，而不是取代應用程式設定載入功能。
Java 的 Properties 類別與 JSON 採用不同的模型。Properties 是字串鍵值格式；JSON 能表示更多類型，而其物件文字不會保留註解或原始分隔符拼寫。因此，轉換器會產生最終 JSON 表格，而非可逆的格式歷史。當順序、註解或精確的來源結構很重要時，請保留原始 .properties 檔案。
將 properties 文字轉換為 JSON
當您已經知道來源文字，且需要為另一個系統建立 JSON 表示時，請使用下列工作流程。
- 貼上前先解碼來源。先取得完全相同的來源文字。如果檔案是以位元組讀取，請使用應用程式預期的字元集解碼，然後貼上產生的 Unicode 字元。轉換器以 load(Reader) 為模型；它不會重現 load(InputStream) 的 ISO-8859-1 位元組解碼方式。
- 貼上完整的字元文字。包含註解與行接續符。不要自行將文字拆成鍵值列，因為奇數個連續反斜線可能會將數個可見行合併成一個邏輯項目。
- 轉換並檢查結果。轉換器會忽略空白行與整行註解，處理支援的逸出字元與接續符，並對重複鍵套用後值取代。請檢查格式化 JSON 與顯示的唯一鍵數量。
- 將鍵與逸出後的值與來源比較。檢查最終的唯一鍵集合、重複鍵中獲勝的值、逸出的空格或分隔符、Unicode 逸出、控制字元逸出，以及由接續行組成的值。
- 複製 JSON 並驗證應用程式契約。複製完全相同的輸出，然後依據使用該資料的應用程式設定結構描述，驗證必要的鍵與預期類型。由於值會維持為字串，僅在結構描述明確要求時才解析或轉換。請依據使用該資料的應用程式契約驗證類型與必要的鍵，不要只依賴連結的 JSON 驗證器。
Reader 風格解析如何改變結果
轉換器遵循 Java Reader 方法有文件記載的逐行格式。自然行可能以 CRLF、LF、CR 或輸入結尾結束。這些規則說明了為什麼簡單的分行器可能產生不同的鍵值表格。
| 來源建構 | 轉換器行為 | 檢查重點 |
|---|---|---|
| 行尾 | 辨識 CRLF、LF 與 CR 自然行結尾，以及輸入結尾。 | 可見的換行不一定等同於獨立的邏輯項目。 |
| 空白行與註解 | 忽略空白行。第一個非空白字元為 # 或 ! 的行是註解。 | 註解不會出現在 JSON 輸出中。 |
| 鍵與值的分隔符 | 在前導空白之後，第一個未逸出的等號、冒號或 properties 空白會結束鍵。後續空白會被略過；若空白分隔符後有選用的等號或冒號，也會略過。沒有分隔符的行，其值為空。 | 確認每個預期值都屬於正確的鍵。 |
| 逸出的空格與分隔符 | 逸出的分隔符與空格仍會保留為鍵或值的一部分。 | 仔細比較包含空格或常值分隔符的鍵。 |
| 行接續 | 行尾之前若有奇數個連續反斜線，邏輯行便會接續。接續標記、行尾，以及下一個自然行中的前導空格、定位字元或換頁字元都會消失。偶數個反斜線不會造成接續，因為反斜線會彼此逸出。 | 在與來源比較之前，先重新組成邏輯值。 |
| 逸出 | 辨識定位字元、新行、歸位字元、換頁、與反斜線相容的逸出方式，以及由一個小寫 u 加正好四個十六進位數字組成的逸出。另一個字元前的反斜線會移除該反斜線；不會加入八進位或特殊的退格字元行為。 | 格式錯誤的 Unicode 逸出會傳回錯誤，而不會被當成看似合理的資料複製。 |
| 重複鍵 | 以較後的值取代較早的值。 | 最後一次出現的值決定最終成員與值。 |
當 # 或 ! 是第一個非空白字元時，註解規則才適用，因此不應假定行內的 # 會開始註解。若轉換後需要驗證註解、順序、分隔符或精確拼寫，請保留原始檔案。
明確處理類型與重複鍵決策
Java Properties 是字串鍵值模型，因此每個產生的值都會維持為 JSON 字串。true、null、001、1.5 與 2026-07-20 等拼寫不會轉換為 Boolean、null、數字或日期。
如果使用該資料的應用程式預期的是 Boolean、整數、十進位數或日期，請稍後依據權威結構描述進行轉換。自動推測類型可能移除前導零、改變識別碼，或改變應用程式專屬的含義，即使原始 properties 檔案本身有效也一樣。
重複 properties 遵循 Java 的表格取代行為：最後的值優先。例如，先出現 mode=debug，接著出現 mode=release，最終 JSON 成員會是 "mode": "release"。請將顯示的唯一鍵數量與取代後預期的最終鍵集合進行比較。
轉換器的中間記錄沒有繼承的原型。因此，名為 __proto__、constructor 與 toString 的鍵仍會是普通的自有資料，而不會觸發原型行為。這可保護轉換步驟，但使用該資料的應用程式仍需進行其一般的結構描述與安全檢查。
依據應用程式驗證 JSON
語法轉換成功，並不能證明結果符合目標系統的設定契約。轉換器不知道您必要的鍵、應用程式專屬類型或部署慣例。
| 應用程式問題 | 轉換所確立的內容 | 仍須驗證的內容 |
|---|---|---|
| 所有必要成員是否都存在？ | JSON 包含最終解析出的唯一鍵集合。 | 將這些鍵與應用程式的必要鍵結構描述進行比較。 |
| 值類型是否正確？ | 所有 property 值都已序列化為 JSON 字串。 | 僅套用應用程式結構描述明確定義的轉換。 |
| 物件是否具有必要的形狀？ | 輸出是依解析出的 property 表格建立的 JSON 物件。 | 確認使用者想要的是該結構，而不是不同的結構描述。 |
| 預設值或預留位置是否已解析？ | 不會評估預設值鏈、環境變數插值、變數展開、Spring profile 或類似的框架規則。 | 在擁有這些值的應用程式或部署系統中解析它們。 |
| 是否需要來源歷史？ | JSON 中不會表示註解、原始分隔符與原始順序。 | 當這些歷史很重要時，保留 .properties 來源。 |
請以 Java 應用程式作為最終參考。將瀏覽器輸出與應用程式實際載入的設定進行比較，確認每個必要的鍵都存在，然後才替換現有的設定檔。
編碼、範圍與大小限制
瀏覽器已提供 Unicode 字元，因此此工作流程以解碼後的文字模擬 load(Reader)。它不會模擬 load(InputStream) 執行的 ISO-8859-1 位元組解碼。貼上前，請使用預定字元集解碼以位元組為主的來源檔案；否則錯誤的字元可能會成為 JSON 的一部分。
- 輸入：只貼上字元文字。這個頁面不會上傳檔案，轉換作業會在本機執行。
- 執行：轉換器不會連線至 Java 程序或執行程式碼。
- 框架功能：預設值鏈、XML properties、環境變數插值、Spring profiles、變數展開、加密密_secret，以及框架專屬的設定規則都不在其範圍內。
- 大小：限制為 500,000 個輸入字元、20,000 個邏輯項目，以及 2,000,000 個輸出字元。
- 失敗行為：超過上限時不會傳回部分 JSON，因此在假定結果完整前，請先檢查報告的限制。
- 密鑰：不要將正式環境中的密鑰貼到不受信任的目的地，也不要隨意分享複製的輸出。本機轉換並不會從 JSON 文字中移除密鑰。
何時 Java 程式碼是更合適的邊界
如果必須在應用程式啟動期間產生 JSON，請將轉換保留在應用程式的 Java 程式碼路徑中。使用 load(Reader) 將字元載入 java.util.Properties，然後將預期的項目傳給應用程式已使用的 JSON 序列化器。Oracle 的 java.util.Properties 文件說明了 Reader 載入契約；Properties API 本身並不是 JSON 序列化器。
- 使用預定字元集解碼來源位元組，並開啟 Reader。
- 建立 Properties 執行個體並呼叫 load(reader)。
- 選取要匯出的項目，並刻意解析任何預設值，而不是無意間將它們混在一起。
- 使用應用程式的 JSON 程式庫序列化預期的鍵值對；除非結構描述定義了轉換，否則保留字串。
- 驗證必要的鍵，並在目標應用程式中測試結果。
瀏覽器轉換器適合用於檢查已知的 Unicode 文字或產生候選 JSON 檔案。它無法執行這條 Java 路徑，因此自行載入該檔案的應用程式仍是最終權威。
可靠的交接檢查清單
在取代線上設定之前，請完成以下檢查：
- 保留原始的 .properties 檔案，以利查看註解、順序及復原。
- 確認唯一鍵數量與預期的最終表格相符。
- 抽樣檢查轉義值、續行串接及重複鍵的勝出項目。
- 將 JSON 語法驗證與必要鍵及類型驗證分開進行。
- 部署前，將結果與目標 Java 應用程式進行比較。