API版本治理与媒体类型协商最佳实践

一、解析与默认策略type Req = { headers: Record<string, string | undefined>; path: string }

type Res = { setHeader: (k: string, v: string) => void; status: (n: number) => Res; end: (b?: string) => void }

function parseAccept(accept: string | undefined): { type: string; version?: number } {

const a = accept || ''

const m = a.match(/application\/vnd\.app\+json;\s*version=(\d+)/i)

if (m) return { type: 'application/vnd.app+json', version: Number(m[1]) }

if (a.includes('application/json')) return { type: 'application/json' }

return { type: '' }

}

const DEFAULT_VERSION = 1

const MAX_VERSION = 3

二、版本选择与校验function selectVersion(acc: { type: string; version?: number }): number {

if (acc.version && acc.version >= 1 && acc.version <= MAX_VERSION) return acc.version

return DEFAULT_VERSION

}

function unsupported(acc: { type: string; version?: number }): boolean {

if (acc.type === '') return true

if (acc.version && (acc.version < 1 || acc.version > MAX_VERSION)) return true

return false

}

三、路由映射与响应type Handler = (req: Req, res: Res) => void

const routes: Record<string, Record<number, Handler>> = {

'/users': {

1: (req, res) => { res.setHeader('Content-Type', 'application/vnd.app+json; version=1'); res.end(JSON.stringify({ users: [{ id: 1, name: 'a' }] })) },

2: (req, res) => { res.setHeader('Content-Type', 'application/vnd.app+json; version=2'); res.end(JSON.stringify({ data: { users: [{ id: 1, name: 'a', email: 'x@y' }] } })) },

3: (req, res) => { res.setHeader('Content-Type', 'application/vnd.app+json; version=3'); res.end(JSON.stringify({ result: { items: [{ id: 1, name: 'a', email: 'x@y', roles: ['user'] }] } })) }

}

}

四、协商流程与验收function handle(req: Req, res: Res) {

const acc = parseAccept(req.headers['accept'])

if (unsupported(acc)) return res.status(406).end('not_acceptable')

const v = selectVersion(acc)

const table = routes[req.path]

const h = table?.[v]

if (!h) return res.status(404).end('not_found')

h(req, res)

}

Accept解析支持`application/vnd.app+json; version=N`与`application/json`；默认版本回退到`1`；最大版本为`3`。不支持版本或类型返回`406`；响应头包含版本化`Content-Type`；路由映射按版本选择。