本文同步發表於個人部落格：FHIR 伺服器的處理錯誤
火線超人可能同時查好幾家醫院的資料。
它的規格裡有一條寫得很死。每一台伺服器的查詢都有各自的逾時上限，預設五秒。一台逾時或出錯，絕對不能影響其他台的結果。例外必須在那一台的查詢內部就攔下來。轉成那台的錯誤狀態，不准往上到 webhook 層。
還有一個地方要特別說明一下。一般查詢預設抓三個月。如果三個月內一筆都沒有、而且至少有一台回 ok，服務會自動改抓十二個月再查一次。但只要每一台都失敗或都需要重新授權，就維持三個月不動。
這條規則背後是一個判斷：「查不到」跟「查失敗」是兩件不同的事。分不清楚的程式會在全部失敗的時候跑去改抓十二個月。做了白工，還讓使用者以為只是資料比較舊。
今天我們就來處理這件事：要怎麼分辨伺服器到底在跟你說什麼呢？
到目前為止這個 app 的每個請求都成功了。要處理錯誤，得先有錯誤。
我對這台 sandbox 試了五種弄壞它的方式，全部觸發成功：
第三列就是今天最重要的一件事。
FHIR 規範定義了 OperationOutcome 這個資源，專門用來回報錯誤。教科書上的錯誤處理就是解析它。
但那個 401 回來的是這樣：
HTTP/1.1 401 Unauthorized
Content-Type: text/plain; charset=utf-8
Invalid token: jwt malformed
沒有 JSON，沒有 issue 陣列，就一句純文字。
原因很合理：這個錯誤是授權層擋下來的，請求根本沒走到 FHIR 伺服器。授權層不是 FHIR 伺服器，它沒有義務回 FHIR 資源。
所以下面這種寫法會在這裡爆掉：
if (!response.ok) {
const outcome = await response.json() // 401 走到這裡直接丟例外
showError(outcome.issue[0].diagnostics)
}
而且爆掉的方式很低級。使用者看到的不是「請重新登入」，是一個 JSON 解析失敗的訊息。那跟真正的問題完全無關，工程師照著去查也查不到。
先看 Content-Type 再決定怎麼解析，這是這篇最實用的一行：
const contentType = response.headers.get('content-type') ?? ''
if (/\bjson\b/i.test(contentType)) {
// 解析 OperationOutcome
} else {
// 當純文字讀
}
用正則是因為 media type 的大小寫不固定。Application/FHIR+JSON 也合法，includes('json') 會漏掉它，把一份 OperationOutcome 當純文字讀。
看一筆實際回來的：
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "Resource Observation/no-such-observation-xyz is not known"
}
]
}
issue 是陣列，一次可以回報好幾個問題。severity 有四種：fatal、error、warning、information。所以要先挑出真正擋住你的那些：
const blocking = issues.filter(
(issue) => issue.severity === 'error' || issue.severity === 'fatal'
)
const pick = (blocking.length ? blocking : issues)[0]
接下來是關鍵：diagnostics 不能直接拿給使用者看。
看看這台實際吐出來的東西：
Failed to parse request body as JSON resource. Error was:
Failed to parse JSON encoded FHIR content: java.io.EOFException:
End of input at line 1 column 31 path $.resourceType
java.io.EOFException 出現在使用者的畫面上，那是把伺服器的內部實作洩漏出去。而使用者完全無法從中知道該怎麼辦。
給人看的那一句應該讀 details.text。那個欄位是規範留給「寫給人看的說明」的地方。但這台的五種錯誤沒有一個帶 details，全部只有 diagnostics。
所以要有一套自己準備的訊息，按狀態碼對照：
const BY_STATUS = {
400: '送出去的內容有問題，請檢查欄位。',
401: '授權已失效，請重新授權。',
403: '這個帳號沒有權限做這件事。',
404: '找不到這筆資料。',
429: '請求太頻繁，請稍後再試。',
500: '伺服器出錯了，稍後再試一次。',
}
優先序是：details.text 有就用它，沒有就退到這張表。diagnostics 一律進 console 給工程師，不上畫面。
錯誤要分兩類，因為處置方式完全不同。
可重試的是「再送一次可能就好了」：伺服器忙不過來、暫時性的網路問題、被限流。這類的處置是等一下再試，使用者甚至不必知道。
const RETRIABLE = new Set([429, 500, 502, 503, 504])
不可重試的是你自己送錯了。400 是這個請求伺服器處理不了，401 是授權無效，404 是東西不在。這些重試一百次結果都一樣，重試只是在浪費時間跟伺服器資源。
有一個要特別小心：401 不能無腦重試。你可能會想「token 過期了，refresh 一次再送」。token 剛好過期時，這是對的。
但 401 的成因不只有過期。token 被撤銷、或是格式根本就壞掉，也都是 401。這兩種 refresh 完再送還是 401，就變成無限迴圈。
順帶講一個常見的誤會：scope 不夠通常不是 401。RFC 6750 給它配的是 403 的 insufficient_scope，401 配的是 invalid_token，也就是過期、撤銷、格式錯。拿到那種 403 時 refresh 沒用，要重新授權把缺的 scope 要回來。
fhirclient 的選擇更保守。我翻了它的原始碼，它在送出請求之前就先看要不要換 token。三個條件要一起成立：有 access_token、有 refresh_token、離過期不到十秒。
但 401 真的回來之後，它一次都不重試，直接把整個 session 清掉要你重新授權。debug 訊息寫得很白：Auto-refresh failed! Please re-launch the app.
要誠實講一件事：今天這五種情境全部落在不可重試那一組。可重試那條路的程式碼寫得出來，但你在這裡驗證不了它，別把它當成測過的東西。
client.request()，它丟什麼上面那些都是自己用 fetch 打出來的。但第三幕的主線是 client.request()，它失敗時丟的東西長得不一樣。
我把 fhirclient 那個 vendor 檔翻開來看了。它丟的是一個 HttpError，繼承自 Error：
class HttpError extends Error {
constructor(response) {
super(`${response.status} ${response.statusText}\nURL: ${response.url}`)
this.name = 'HttpError'
this.response = response
this.statusCode = response.status
this.status = response.status
this.statusText = response.statusText
}
}
error.message 開頭兩行是狀態碼加 statusText，然後是網址：
404
URL: https://launch.smarthealthit.org/v/r4/sim/…/fhir/Observation/no-such-observation-xyz
404 後面那個空格不是排版失誤，這台 sandbox 的 statusText 是空字串。
那 OperationOutcome 呢？直覺會想：Response 就掛在 error.response 上，clone 一份餵給 describeFailure() 不就好了。
這條路走不通。看 fhirclient 收到回應後的那個檢查：
async function checkResponse(response) {
if (!response.ok) {
const error = new HttpError(response)
throw (await error.parse(), error)
}
return response
}
throw 之前先 await error.parse()。而 parse() 會讀 body：
async parse() {
if (!this.response.bodyUsed) {
const type = this.response.headers.get('content-type') || 'text/plain'
if (type.match(/\bjson\b/i)) {
this.message += '\n\n' + JSON.stringify(await this.response.json(), null, 4)
} else if (type.match(/^text\//i)) {
this.message += '\n\n' + (await this.response.text())
}
}
return this
}
（這兩段是照 vendor 檔重排的可讀版。OAuth error 那一支跟外層的 try 都省略了。）
它讀 body 是有條件的，Content-Type 要是 JSON 或 text/ 開頭。這五種都符合。
所以你拿到 HttpError 的時候，body 已經被讀完了，bodyUsed 是 true。這時候呼叫 clone() 不是拿到一個空的 stream，是直接丟 TypeError。
但被讀走的東西沒有消失。parse() 把整個 JSON 用 JSON.stringify 接在 message 後面了。所以剛才那段 message 其實還有下半截：
404
URL: https://launch.smarthealthit.org/v/r4/sim/…/fhir/Observation/no-such-observation-xyz
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "Resource Observation/no-such-observation-xyz is not known"
}
]
}
OperationOutcome 一直都在，只是變成了文字。
所以這條路要讀的是 status 跟 message，不要去碰 response：
export function describeClientError(error) {
if (typeof error?.status === 'number') {
return {
status: error.status,
retriable: isRetriable(error.status),
userMessage: BY_STATUS[error.status] ?? `請求失敗，HTTP ${error.status}。`,
developerMessage: error.message ?? null,
issueCode: null,
issueCount: 0,
}
}
return {
status: 0,
retriable: true,
userMessage: '連不上伺服器，請檢查網路後再試一次。',
developerMessage: error?.message ?? String(error),
issueCode: null,
issueCount: 0,
}
}
issueCode 跟 issueCount 固定是 null 與 0，這是走 client.request() 的代價。你拿得到那段文字，但拿不到一個可以讀 issue[0].code 的物件。真的需要結構化的 issue，就得像前面那樣自己用 fetch，在讀 body 之前先 clone()。
順帶一提，parse() 判斷 content-type 用的是 contentType.match(/\bjson\b/i)。所以前面那一課不是本系列自己發明的慣例，fhirclient 的判斷順序也是先看 content-type 再決定怎麼讀。
上面兩種都假設伺服器有回東西。還有一種情況是根本沒有回應。
斷網、DNS 查不到伺服器的位址、CORS 預檢被擋，這三種是 fetch 自己 reject。丟的是 TypeError 不是 HttpError，身上連 status 都沒有。
所以判斷式問的是「有沒有一個數字的 status」，這就是上面那段 if (typeof error?.status === 'number') 的用意。沒有 status 的那條路當成可重試，因為網路問題常常是暫時的。
但這個分類會漏。CORS 設定錯誤也沒有 status，重試幾次都一樣。
這一類我沒辦法給你實測輸出，你把 Wi-Fi 關掉試一次就會看到。
Console 上的字每家瀏覽器不同，Chrome 是 TypeError: Failed to fetch。重點不是那串字，是型別為 TypeError 而不是 HttpError。
起點是 day18 結束時的專案，加上 write.js。今天新增 errors.js，並在畫面上放六顆按鈕故意觸發失敗。
const BY_STATUS = {
400: '送出去的內容有問題，請檢查欄位。',
401: '授權已失效，請重新授權。',
403: '這個帳號沒有權限做這件事。',
404: '找不到這筆資料。',
410: '這筆資料已經被刪除。',
422: '這筆資料沒通過伺服器的檢查。',
429: '請求太頻繁，請稍後再試。',
500: '伺服器出錯了，稍後再試一次。',
503: '伺服器暫時無法服務，稍後再試一次。',
}
const RETRIABLE = new Set([429, 500, 502, 503, 504])
export function isRetriable(status) {
return RETRIABLE.has(status)
}
function fromOperationOutcome(payload) {
if (payload?.resourceType !== 'OperationOutcome') return null
const issues = payload.issue ?? []
const blocking = issues.filter(
(issue) => issue.severity === 'error' || issue.severity === 'fatal'
)
const pick = (blocking.length ? blocking : issues)[0]
if (!pick) return null
return {
userMessage: pick.details?.text ?? null,
developerMessage: pick.diagnostics ?? pick.details?.text ?? null,
issueCode: pick.code ?? null,
issueCount: issues.length,
}
}
fromOperationOutcome 回 null 的情況有兩種：payload 根本不是 OperationOutcome，或者 issue 是空陣列。兩種都要防，因為伺服器回什麼你控制不了。
export async function describeFailure(response) {
const status = response.status
const contentType = response.headers.get('content-type') ?? ''
const fallback = BY_STATUS[status] ?? `請求失敗，HTTP ${status}。`
let developerMessage = null
let issueCode = null
let issueCount = 0
let userMessage = null
if (/\bjson\b/i.test(contentType)) {
try {
const parsed = fromOperationOutcome(await response.json())
if (parsed) {
userMessage = parsed.userMessage
developerMessage = parsed.developerMessage
issueCode = parsed.issueCode
issueCount = parsed.issueCount
}
} catch {
developerMessage = '回應宣稱是 JSON 但解不開'
}
} else {
developerMessage = (await response.text()).slice(0, 200)
}
return {
status,
retriable: isRetriable(status),
userMessage: userMessage ?? fallback,
developerMessage,
issueCode,
issueCount,
}
}
那個 try 不是多餘的。Content-Type 說是 JSON，不代表 body 真的是合法 JSON。代理伺服器或閘道器塞一頁 HTML 錯誤頁進來，是很常見的事。
.slice(0, 200) 是因為純文字錯誤可能是一整頁 HTML，不截斷會把 console 洗版。
六顆按鈕，前五顆對應前面那五種弄壞的方式：
const FAILURE_CASES = {
notfound: (base) => [`${base}/Observation/no-such-observation-xyz`, {}],
badparam: (base) => [`${base}/Observation?totally-not-a-param=1`, {}],
badtoken: (base, patientId) => [
`${base}/Patient/${patientId}`,
{ headers: { Authorization: 'Bearer not-a-real-token' } },
],
mismatch: (base) => [
`${base}/Observation`,
{
method: 'POST',
headers: { 'Content-Type': 'application/fhir+json' },
body: JSON.stringify({ resourceType: 'Patient' }),
},
],
// 不是送錯型別，是根本收不了尾。Content-Type 說是 JSON，body 不是。
badjson: (base) => [
`${base}/Observation`,
{
method: 'POST',
headers: { 'Content-Type': 'application/fhir+json' },
body: '{"resourceType": "Observation"',
},
],
}
第六顆叫 clientfail，走的是 client.request() 不是 fetch，所以不在表裡：
import { describeFailure, describeClientError } from './errors.js'
async function tryFailure(client, name) {
try {
if (name === 'clientfail') {
await client.request('Observation/no-such-observation-xyz')
return // 這個請求必定失敗，走到這裡代表伺服器行為與預期不符
}
const [url, init] = FAILURE_CASES[name](client.state.serverUrl, client.patient.id)
report(name, await describeFailure(await fetch(url, init)))
} catch (error) {
report(name, describeClientError(error))
}
}
function report(name, failure) {
console.log(`[${name}]`, failure.status, failure.retriable ? '可重試' : '不重試')
console.log(' 給使用者：', failure.userMessage)
console.log(' 給開發者：', failure.developerMessage)
errorResult.className = 'mt-2 text-sm text-rose-700'
errorResult.textContent = `HTTP ${failure.status}：${failure.userMessage}`
}
errorResult 是畫面上那行紅字，在檔案開頭抓好：
const errorResult = document.querySelector('#error-result')
按鈕的事件綁定放在 showPatient() 裡，要等授權完成拿到 client 才綁得上：
for (const button of document.querySelectorAll('[data-case]')) {
button.addEventListener('click', () => tryFailure(client, button.dataset.case))
}
那個 try 一次管兩件事。一是接住 clientfail 丟的 HttpError，交給 describeClientError。二是接住斷網時 fetch 丟的 TypeError，把 Wi-Fi 關掉再按前五顆就會走到。少了它，斷網就是一個沒人接的 Promise rejection，畫面什麼都不會動。
base 傳的是 client.state.serverUrl。那是 fhirclient 存 FHIR base URL 的地方，day18 寫入時用的也是它。病人 id 從 client.patient.id 傳進去，不要寫死，換一位病人才不用改程式。
實際跑出來的結果：
畫面上只出現「給使用者」那一句，java.io.EOFException 那類東西留在 console。
三種 400 的「給使用者」那一句完全相同，因為這台沒有一個 OperationOutcome 帶 details.text。實際除錯要看 console 那一行，三者各有一個好認的關鍵字。搜尋參數打錯是 Unknown search parameter，資源型別不符是 Incorrect resource type found，body 不是合法 JSON 則會出現 java.io.EOFException。
畫面上分不出來的三種錯誤，在 console 裡一眼就分得出來。這就是「diagnostics 留給 console」的實際用處。
notfound 跟 clientfail 也共用同一句，兩者都是 404。但 console 那一行差很多。notfound 印的是 describeFailure() 從 OperationOutcome 挑出來的 diagnostics。clientfail 印的是整個 HttpError 的 message，裡面有 parse() 接上的完整 JSON。
特別看 badtoken 那次。程式沒有丟例外，照樣產出一句可讀的訊息，這就是先看 Content-Type 換來的。
回到開頭那些規則，現在它們比較好懂了。
每台伺服器各自算逾時，例外就地攔下。 一台醫院掛掉，使用者應該看到其他幾家的資料，加上一句「某某醫院暫時連不上」。整個畫面空白是最糟的選項。
token 過期的伺服器標成需要重新授權，不查詢。 這是把錯誤再細分。有一種失敗的正確處置既不是重試也不是放棄，是請使用者去按一個按鈕。
全部失敗時不改抓十二個月。 因為那時候你根本不知道有沒有資料，改了只是再失敗一次。
三條規則的共同點是一句話。錯誤不是布林值，它有種類，不同種類要走不同的路。
完整可跑的版本在 GitHub 上的 day19-error-handling，想先看跑起來的樣子可以直接開線上版。
先看 Content-Type 再解析，diagnostics 留給 console。可重試與不可重試要分開，而 401 不能無腦重試。
明天處理量的問題。今天這位病人只有三筆病況兩筆用藥，資料一頁就裝完了。真實病歷不會這麼客氣，而 FHIR 的分頁機制跟你想像的不一樣。
iThome鐵人賽
看影片追技術