黑河市all最近在做一个医疗健康类系统的对接，要把第三方平台的患者档案和检验观察数据拉到自己的应用里。对方开放的是FHIR标准的REST接口，核心操作就是资源查询。刚开始我以为这活儿简单——不就是调HTTP接口、读JSON、拿到数据映射一下吗？真正上手才发现，FHIR的查询从URL设计到响应解析都有不少讲究，尤其是当你在Postman里手动调试得心应手，转头要用Java客户端把它工程化的时候，很多问题才会浮出来。
这篇文章不看官方文档的枯燥定义，纯粹从"我要拿到数据"这个诉求出发，先带你用HTTP接口把FHIR资源查询的底层逻辑摸清楚，再落到Java客户端（以HAPI FHIR为主）的完整实现上。适合刚接触FHIR的Java后端开发、医技系统集成工程师，以及任何需要在业务系统里对接FHIR服务的同学参考。
1. FHIR不是一张表：先建立对资源模型的查询直觉
1.1 为什么很多"老接口玩家"会懵
过去做接口对接，我们的直觉是：每个业务对象对应一张表、一个接口、几个必传参数。比如查用户就是GET /api/users?id=123，查订单就是GET /api/orders?orderNo=xxx。但FHIR完全不是这个思路。
FHIR全称是Fast Healthcare Interoperability Resources，标准由HL7组织维护，核心思想是"资源"。一个患者是一个Patient资源，一次检验结果是一堆Observation资源，一次就诊是一条Encounter。每种资源有自己固定的字段结构，但不同的系统在实现时允许存在差异——可扩展性极强，但对后端开发者来说，这种"统一中的不统一"往往是学习时最大的坎。
举个例子，你要查一个患者的名字。在FHIR里，Patient资源有一个name字段，但它的类型不是简单的字符串，而是一个HumanName复合结构，里面可以拆成given、family、prefix、suffix，还可以有多个名字条目。你用HTTP接口查询时，如果不知道这个结构，很可能在解析返回数据时一头雾水。
所以，做FHIR资源查询第一件事不是写代码，而是建立"资源树"的概念：先确定你要查什么类型的资源，再确认这种资源上有哪些搜索参数，最后才谈得上怎么组装查询请求。
1.2 资源交互操作：READ、SEARCH，以及更多
FHIR对资源的操作有一套标准的RESTful交互约定，这也是从HTTP接口切入最舒服的地方。常用操作包括：
| 交互 | HTTP方法 | 路径示例 | 用途 |
|---|---|---|---|
| read | GET | [base]/Patient/123 |
按ID读取单个资源 |
| vread | GET | [base]/Patient/123/_history/45 |
按ID和版本号读取历史版本 |
| search | GET | [base]/Patient?family=张 |
按条件搜索资源 |
| create | POST | [base]/Patient |
新建资源 |
| update | PUT | [base]/Patient/123 |
全量更新资源 |
| patch | PATCH | [base]/Patient/123 |
部分更新资源 |
| delete | DELETE | [base]/Patient/123 |
删除资源 |
标题里的"资源查询"，绝大多数场景走的是read和search这两个操作。read很直白，就是"我知道资源ID，我要取它的完整内容"；search则是"我不知道ID，或者我要按一批条件筛选资源"。从接口调试的角度看，这俩操作是第一步，也是后面用Java客户端封装的主战场。
1.3 资源版本与兼容性：R4、R4B，别选错
写代码之前必须先确认服务器用的FHIR版本。目前主流是R4（4.0.1），但也有不少系统还在用DSTU2、STU3，或者已经切到R4B、R5。不同版本之间资源字段有差异，比如R5里部分资源的结构做过调整，HAPI FHIR对不同版本所依赖的maven包也不同。
我自己踩过最典型的坑就是：服务器是R4，本地依赖却用的是hapi-fhir-structures-r4对应的版本没问题，但如果服务器其实返回的是STU3格式，HAPI在解析时会直接抛DataFormatException，错误信息又长又绕。所以接任何FHIR服务，第一件事是拿到它的CapabilityStatement（通常GET [base]/metadata即可），确认支持的版本号和资源类型列表。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 手写HTTP查询请求：从URL、查询参数到Bundle响应
2.1 一条完整查询请求的组成
一条FHIR资源查询URL，从结构上说就是：
code复制GET [base]/[ResourceType]?[searchParams]&[paginationParams]&[formatParams]
拆开来看：
[base]是服务的基础地址，比如https://fhir.example.com/fhir，注意这个路径是可配置的，有的服务直接暴露根路径，有的挂在二级目录下。[ResourceType]是你要查的资源类型，如Patient、Observation、MedicationRequest。[searchParams]是查询条件，标准的搜索参数随资源类型不同而变化。[paginationParams]是分页参数，常用_count、_offset或_page。[formatParams]是用_format指定返回格式，如_format=json或_format=xml。
最朴素的请求可能就是这样的：
code复制GET https://fhir.example.com/fhir/Patient?family=张&_count=20&_format=json
从HTTP接口角度来说，看懂这条URL，就相当于掌握了FHIR查询的门面。至于返回来的数据，FHIR规定搜索响应统一包装在Bundle资源里。这个设计很多人第一次接触会觉得绕：明明是查Patient，返回的却是一个Bundle，Patient是在Bundle的entry列表里一个个包着的。原因是FHIR希望搜索返回的数据携带上下文，比如分页链接、匹配总数、检索状态等，所以套了一层壳。
2.2 搜索参数的类型与使用：别把字符串查询神话了
FHIR的search参数大体分几类，理解它们的差异对后面用Java客户端构建查询非常有帮助。
- 字符串参数：作用于
HumanName、Address这类复合字段，比如Patient?name=张。字符串参数有修饰符，比如:exact表示精确匹配，:contains表示包含匹配。 - Token参数：通常用于标识符、CodeableConcept这类字段，比如
Patient?identifier=urn:oid:1.2.3|12345，这里竖线前的部分是系统，竖线后是值。如果只传值不传系统，很多服务器会模糊匹配。 - 日期参数：支持操作符，如
Patient?birthdate=gt1990-01-01表示出生日期晚于1990年1月1日。这里要注意操作符是写在“参数名”位置的，不是值的位置。 - 引用参数：用于关联查询，比如查某位患者的检验结果，可以
Observation?subject=Patient/123。 - 数量参数：比较少见，通常用于血压值这类可以量化的字段。
这些参数类型在Java客户端中都有对应的语法，但它们在底层HTTP层面的表现就是URL里的key-value对。我强烈建议你先手动用curl或Postman把参数调通，再写Java代码，这样出了问题容易定位。
2.3 响应解析：Bundle、Entry与RESTful资源
拿一个查Patient的例子来说，HTTP响应大致长这样（JSON格式）：
json复制{