關於本文
這篇記錄的是我在網站開發中,圍繞 JSON 傳遞資料所遇到的一連串問題與最終解法。專案的資料庫是 MongoDB、後端是 Python、前端採「半分離」形式的 Riot.js——首頁資料由服務端樣板引擎直接渲染進 HTML,避免首頁被載入兩次;其餘動態內容則走 Ajax。整條流程都以 JSON 承載資料,但每個環節的規則不盡相同,坑也各異。

JSON(JavaScript Object Notation)是由道格拉斯·克羅克福特構想的輕量級資料交換格式。它的前輩 XML 或許更廣為人知,但 JSON 並非為了取代 XML 而出現,只是它更精簡、更適合在網頁開發中傳遞資料。從名字就能看出,它的語法沿用 JavaScript 的物件寫法;而類似結構在許多語言裡都有對應,例如 Python 的 dict。 MongoDB 這類文件導向的 NoSQL 資料庫,也直接採用 JSON 風格作為儲存格式。
JSON 描述的資料結構包含:物件 {key: value}、陣列 [obj, obj, ...]、字串、數字與布林值。它的價值在於讓「語言內的變數」與「字串形式的文字」之間可以雙向轉換。
這一段最輕鬆,PyMongo、Motor 等驅動把介面封裝得很友善,你基本上只是在操作 Python 原生 dict:
import motor
client = motor.motor_tornado.MotorClient()
db = client['test']
user_col = db['user']
user_col.insert(dict(
name = 'Yu',
is_admin = True,
))
唯一要留意的是 MongoDB 的主鍵 _id 以 ObjectId("572df0b78a83851d5f24e2c1") 形式儲存,對應到 Python 是 bson.objectid.ObjectId,查詢時必須用這個型別的實例:
from bson.objectid import ObjectId
user = db.user.find_one(dict(
_id = ObjectId("572df0b78a83851d5f24e2c1")
))
HTTP 上傳的其實全是二進位資料,不存在什麼 JSON,但我們可以透過 Header 的 Content-Type 告訴前端「請用什麼方式解讀」。傳 JSON 時設為 application/json,在 Tornado 新版本中甚至可以直接寫入 dict:
# Handler
async def post(self):
user = await self.db.user.find_one({})
self.write(user)
然後就收到第一個錯誤:TypeError: ObjectId('...') is not JSON serializable。Tornado 雖然幫我們簡化了流程,但寫入 dict 時內部仍會做一次 json.dumps(),而 ObjectId 對它而言是非法型別。直覺的解法是自訂 encoder:
import json
from bson.objectid import ObjectId
class JSONEncoder(json.JSONEncoder):
def default(self, obj):
if isinstance(obj, ObjectId):
return str(obj)
return super().default(self, obj)
# Handler
async def post(self):
user = await self.db.user.find_one({})
self.write(JSONEncoder.encode(user))
錯誤消失了,但新問題跟著來:經過 encode 之後資料變成字串,Content-Type 也被帶成 text/html,前端收到的是一段文字而非可用的物件。

補救方式之一是讓前端再解析一次:
$.post(API, {}, function(res){
data = JSON.parse(res);
console.log(data._id);
})
此時整條鏈條變成:
Python ==> json.dumps ==> HTTP ==> JavaScript ==> JSON.parse dict ==> str ==> binary ==> string ==> Object
接著第二個問題浮現:只要資料中出現特殊字元,JSON.parse 就會爆掉。
JSON.parse("{'abs': '\n'}");
// Uncaught SyntaxError: Unexpected token ' in JSON at position 1
這正是「只忙著滅火」的連鎖代價。回頭沿著鏈條往上找,答案其實很樸素:規則遇到特例時,應該讓特例去適應規則,而不是改規則。
# Handler
async def post(self):
user = await self.db.user.find_one({})
user['_id'] = str(user['_id'])
self.write(user)
若回傳的是列表,就在遍歷時一併處理:
# DB
async def get_top_users(self, n = 20):
users = []
async for user in self.db.user.find({}).sort('rank', -1).limit(n):
user['_id'] = str(user['_id'])
users.append(user)
return users
除了 Ajax 的部分,頁面上其餘資料是後端樣板渲染出來的,也就是被寫死成 HTML。在我們希望資料直接塞進 <script> 標籤、讓瀏覽器執行時就能取用。嚴格說這不算 JSON 應用,而是 Python dict 到 JavaScript Object 的直接轉換。常規寫法如下:
# Handler
async def get(self):
users = self.db.get_top_users()
render_data = dict(users = users)
self.render('users.html', **render_data)
<!-- HTML + Riot.js -->
<app></app>
<script>
riot.mount('app', {
users: [
{% for user in users %}
{ name: "{{ user['name']}}", is_admin: "{{ user['is_admin']}}" },
{% end %}
],
})
</script>
這樣寫是對的,但引号與 ObjectId 的問題仍要額外處理。我也試過一個繞路的做法:
# Handler
async def get(self):
users = self.db.get_top_users()
render_data = dict(users = JSONEncoder.encode(users))
self.render('users.html', **render_data)
<!-- HTML + Riot.js -->
<app></app>
<script>
riot.mount('app', {
users: JSON.parse('{{ users }}'),
})
</script>
但這和第三節的錯誤本質相同。樣板渲染與 HTTP 傳輸的規則類似,差別只在於樣板裡的字串變數是「純值、沒有引号」,所以最乾淨的作法是直接把它當成 JavaScript 腳本輸出({% raw ... %} 是 Tornado 樣板防止符號被 HTML 編碼的語法):
<!-- HTML + Riot.js -->
<app></app>
<script>
riot.mount('app', {
users: {% raw users %},
})
</script>
JSON 好用,但跨語言環境時細節很多:ObjectId 的序列化、Content-Type 的連帶影響、特殊字元造成的解析失敗,往往會一題引出一題。與其在下游層層補洞,不如回到源頭把型別處理乾淨。而「遇到特例時改變自己、而非改變規則」這條原則,對那些已被廣泛採用的慣例尤其適用。