HAPI FHIR 快速上手教程

HAPI FHIR 快速上手建议先用 Docker 跑通 JPA Server，再在 Web Tester 里练习 CRUD，最后用 Java 客户端写一个 Patient 读写示例。

1. 先跑一个本地 FHIR 服务器

最省事的办法是用官方 JPA Server starter 项目。

git clone https://github.com/hapifhir/hapi-fhir-jpaserver-starter.git
cd hapi-fhir-jpaserver-starter
docker compose up -d

启动后访问：

http://localhost:8080/fhir

如果不用 Docker，也可以用 Maven 跑：

git clone https://github.com/hapifhir/hapi-fhir-jpaserver-starter.git
cd hapi-fhir-jpaserver-starter
mvn clean install
mvn jetty:run

端口、数据库和 FHIR 版本以当前仓库 README 为准。

2. 用 Web Tester 熟悉接口

HAPI FHIR JPA Server 自带 Web Tester，可以在浏览器里直接试请求。

常见操作：

GET  /fhir/metadata
GET  /fhir/Patient
GET  /fhir/Patient?name=Alice
POST /fhir/Patient
PUT  /fhir/Patient/{id}

可以先试：

GET http://localhost:8080/fhir/Patient

返回一个 Bundle，说明服务器已经正常响应。

3. 手动创建一个 Patient

用 curl 或 Postman 发送：

curl -X POST http://localhost:8080/fhir/Patient \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "Patient",
    "name": [
      {
        "family": "Zhang",
        "given": ["Wei"]
      }
    ],
    "gender": "male",
    "birthDate": "1990-05-12"
  }'

成功后会返回新 Patient 的 id，例如：

Patient/12345

再查询它：

curl http://localhost:8080/fhir/Patient/12345

4. 用 Java 客户端读写资源

在 Maven 项目里加入 HAPI FHIR 依赖，版本以官方发布为准。

<dependency>
    <groupId>ca.uhn.hapi.fhir</groupId>
    <artifactId>hapi-fhir-client</artifactId>
    <version>7.x.x</version>
</dependency>

写一个简单示例：

import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.rest.client.api.IGenericClient;
import org.hl7.fhir.r4.model.Patient;

public class HapiFhirClientDemo {
    public static void main(String[] args) {
        FhirContext ctx = FhirContext.forR4();
        IGenericClient client = ctx.newRestfulGenericClient(
            "http://localhost:8080/fhir"
        );

        Patient patient = new Patient();
        patient.addName()
               .setFamily("Li")
               .addGiven("Ming");
        patient.setGender(org.hl7.fhir.r4.model.Enumerations.AdministrativeGender.MALE);
        patient.setBirthDateAsString("1988-03-21");

        Patient created = client.create()
                                .resource(patient)
                                .execute();

        System.out.println("Created Patient: " + created.getId());

        Patient read = client.read()
                             .resource(Patient.class)
                             .withId(created.getIdElement())
                             .execute();

        System.out.println("Patient name: " + read.getNameFirstRep().getFamily());
    }
}

5. 再试一个 Observation

FHIR 里临床数据通常用 Observation 表示，比如体温、血压、血糖。

curl -X POST http://localhost:8080/fhir/Observation \
  -H "Content-Type: application/json" \
  -d '{
    "resourceType": "Observation",
    "status": "final",
    "code": {
      "coding": [
        {
          "system": "http://loinc.org",
          "code": "8310-5",
          "display": "Body temperature"
        }
      ]
    },
    "valueQuantity": {
      "value": 37.2,
      "unit": "°C",
      "system": "http://unitsofmeasure.org",
      "code": "Cel"
    },
    "subject": {
      "reference": "Patient/12345"
    }
  }'

查询该患者的观察值：

curl "http://localhost:8080/fhir/Observation?subject=Patient/12345"

6. 继续深入可以看这些

7. 常见坑

• 端口不一定是 8080：以实际 Docker 或 Maven 启动日志为准。
• FHIR 版本要对齐：R4、STU3、R5 的资源结构不同。
• JPA Server 不等于生产系统：默认配置适合学习和测试，生产环境要补数据库、权限、审计和备份。
• 不要暴露公网：本地测试可以，上线前必须加认证、HTTPS 和访问控制。
• 版本要更新：HAPI FHIR 迭代较快，使用前建议检查最新安全公告和版本说明。