Haskell中REST API多版本库最优实现：避免重复与双版本共存

我之前维护过支持多版本REST API的Haskell客户端，完全懂你这种既要减少代码重复、又要避开重复实例错误、还要同时用两个版本的痛点。下面几个方案亲测有效，你可以根据自己的代码结构选：

方案1：用Newtype包装核心类型，分离JSON实例 #

这是最直观也最常用的方案，核心思路是把**无版本差异的逻辑（类型定义、API调用）**放在公共模块，然后为每个API版本创建独立的Newtype包装器，在版本模块里单独实现JSON实例。

具体步骤： #

1. 提取公共核心模块：把共享的类型、API调用逻辑抽出来，比如：

-- Core/Types.hs
data UserCore = UserCore
  { userId :: Int
  , userName :: Text
  , userEmail :: Text
  } deriving (Generic, Show)

-- Core/API.hs
import Core.Types
import Network.HTTP.Client
import Data.Aeson

-- 通用API调用函数，只关心JSON解码和端点，不绑定版本
fetchUserGeneric :: FromJSON a => String -> Int -> Manager -> IO (Either String a)
fetchUserGeneric baseEndpoint userId manager = do
  let url = baseEndpoint <> "/users/" <> show userId
  request <- parseRequest url
  response <- httpLbs request manager
  pure $ eitherDecode' (responseBody response)

2. 为每个版本创建独立模块：用Newtype包装核心类型，实现该版本特有的JSON实例：

-- API/V1/User.hs
import Core.Types
import Data.Aeson

newtype User = User UserCore deriving (Generic, Show)

-- V1的JSON字段是驼峰式（比如userId对应"userId"）
instance FromJSON User where
  parseJSON = genericParseJSON defaultOptions

-- 导出V1专属的API调用函数
fetchV1User :: Int -> Manager -> IO (Either String User)
fetchV1User = fetchUserGeneric "https://api.example.com/v1"

-- API/V2/User.hs
import Core.Types
import Data.Aeson

newtype User = User UserCore deriving (Generic, Show)

-- V2的JSON字段是下划线式（比如userId对应"user_id"）
instance FromJSON User where
  parseJSON = genericParseJSON defaultOptions
    { fieldLabelModifier = camelTo2 '_' . drop 4 -- 去掉前缀"user"，转下划线
    }

-- 导出V2专属的API调用函数
fetchV2User :: Int -> Manager -> IO (Either String User)
fetchV2User = fetchUserGeneric "https://api.example.com/v2"

3. 客户端同时使用两个版本：通过限定模块名区分类型，完全不会冲突：

-- Client.hs
import API.V1.User as V1
import API.V2.User as V2
import Network.HTTP.Client

main :: IO ()
main = do
  manager <- newManager defaultManagerSettings
  v1User <- V1.fetchV1User 123 manager
  v2User <- V2.fetchV2User 123 manager
  print v1User
  print v2User

优势： #

• 核心代码只写一次，bug修复、逻辑升级只需改公共模块
• 每个版本的JSON实例完全独立，不会触发重复实例错误
• 客户端可以明确区分不同版本的类型，避免混用

方案2：用类型类抽象版本差异（进阶） #

如果你的版本差异不止JSON实例，还有请求头、参数格式等，可以用类型类把版本相关的行为抽象出来，进一步复用逻辑：

-- Core/Version.hs
data V1
data V2

class APIVersion v where
  baseEndpoint :: Proxy v -> String
  userDecoder :: Proxy v -> Value -> Parser UserCore

-- 通用API调用，用类型类约束版本行为
fetchUser :: APIVersion v => Int -> Manager -> IO (Either String UserCore)
fetchUser userId manager = do
  let endpoint = baseEndpoint (Proxy :: Proxy v)
  request <- parseRequest $ endpoint <> "/users/" <> show userId
  response <- httpLbs request manager
  pure $ parseEither (userDecoder (Proxy :: Proxy v)) (responseBody response)

-- API/V1.hs
instance APIVersion V1 where
  baseEndpoint _ = "https://api.example.com/v1"
  userDecoder _ = genericParseJSON defaultOptions

-- API/V2.hs
instance APIVersion V2 where
  baseEndpoint _ = "https://api.example.com/v2"
  userDecoder _ = genericParseJSON defaultOptions
    { fieldLabelModifier = camelTo2 '_' . drop 4
    }

客户端使用时通过类型注解区分版本：

v1User <- fetchUser @V1 123 manager
v2User <- fetchUser @V2 123 manager

优势： #

• 版本差异集中在类型类实例里，逻辑更清晰
• 核心API函数完全通用，无需为每个版本重复写包装函数

避坑提醒 #

• 不要尝试在不同模块为同一个核心类型写JSON实例，Haskell的孤儿实例规则会直接报错，Newtype包装是绕开这个问题的标准做法
• 尽量用Generic自动生成JSON实例，减少手动写parseJSON的重复代码
• 测试时，核心逻辑只需要测一次，版本相关的测试只需要验证JSON编解码和端点正确性

内容的提问来源于stack exchange，提问作者RandomB