hapi-fhir-client
hapi-fhir-client là một thành phần trong hệ sinh thái HAPI FHIR, được phát triển để đơn giản hóa việc tương tác với FHIR servers thông qua RESTful API. Thư viện này được thiết kế với triết lý "fluent interface", cho phép các nhà phát triển xây dựng các request phức tạp một cách trực quan và dễ đọc.
Phiên bản hiện tại hỗ trợ đầy đủ cho FHIR R5 và các phiên bản trước đó (R4, DSTU3, DSTU2), giúp nhà phát triển làm việc liền mạch với nhiều phiên bản FHIR khác nhau.
Tính năng chính
1. GenericClient - Nền tảng tương tác với FHIR servers
IGenericClient là interface trung tâm của thư viện, cung cấp phương thức để thực hiện tất cả các hoạt động RESTful FHIR, từ CRUD cơ bản đến các operations phức tạp hơn:
// Khởi tạo FhirContext
FhirContext ctx = FhirContext.forR5();
// Tạo client kết nối đến FHIR server
IGenericClient client = ctx.newRestfulGenericClient("http://hapi.fhir.org/baseR5");Đối tượng IGenericClient được tạo ra từ FhirContext và là cổng vào cho tất cả các tương tác với FHIR server.
2. Fluent interface cho search queries
Một trong những điểm mạnh của hapi-fhir-client là cú pháp fluent cho phép xây dựng các truy vấn tìm kiếm phức tạp một cách trực quan:
// Tìm kiếm bệnh nhân theo nhiều tiêu chí
Bundle results = client.search()
.forResource(Patient.class)
.where(Patient.FAMILY.matches().value("Nguyễn"))
.and(Patient.BIRTHDATE.after().day("2000-01-01"))
.and(Patient.GENDER.exactly().code("male"))
.sort().descending(Patient.BIRTHDATE)
.count(10)
.returnBundle(Bundle.class)
.execute();Đoạn mã trên xây dựng một truy vấn tìm kiếm bệnh nhân có họ "Nguyễn", sinh sau 2000-01-01, giới tính nam, sắp xếp theo ngày sinh giảm dần và giới hạn 10 kết quả.
3. CRUD operations đơn giản
Thư viện cung cấp các phương thức đơn giản để thực hiện các thao tác CRUD (Create, Read, Update, Delete) cơ bản:
// CREATE - Tạo resource mới
MethodOutcome outcome = client.create()
.resource(patient)
.execute();
String newId = outcome.getId().getIdPart();
// READ - Đọc resource theo ID
Patient retrievedPatient = client.read()
.resource(Patient.class)
.withId(newId)
.execute();
// UPDATE - Cập nhật resource
patient.setActive(true);
client.update()
.resource(patient)
.execute();
// DELETE - Xóa resource
client.delete()
.resourceById("Patient", newId)
.execute();4. Hỗ trợ transaction và batch
Khi cần thực hiện nhiều thao tác trong một request, hapi-fhir-client hỗ trợ cả transaction (toàn bộ thành công hoặc thất bại) và batch (các thao tác độc lập):
// Tạo bundle
Bundle bundle = new Bundle();
bundle.setType(Bundle.BundleType.TRANSACTION);
// Thêm entry tạo bệnh nhân mới
bundle.addEntry()
.setFullUrl("urn:uuid:" + UUID.randomUUID().toString())
.setResource(newPatient)
.getRequest()
.setMethod(Bundle.HTTPVerb.POST)
.setUrl("Patient");
// Thêm entry cập nhật observation
bundle.addEntry()
.setResource(existingObservation)
.getRequest()
.setMethod(Bundle.HTTPVerb.PUT)
.setUrl("Observation/" + existingObservation.getIdElement().getIdPart());
// Thực hiện transaction
Bundle resultBundle = client.transaction()
.withBundle(bundle)
.execute();5. Xử lý phân trang dễ dàng
Khi làm việc với tập dữ liệu lớn, hapi-fhir-client đơn giản hóa việc xử lý phân trang:
// Tìm kiếm với giới hạn kết quả
Bundle results = client.search()
.forResource(Observation.class)
.where(Observation.SUBJECT.hasId("Patient/123"))
.count(20) // 20 kết quả mỗi trang
.returnBundle(Bundle.class)
.execute();
// Duyệt qua kết quả trang đầu tiên
for (BundleEntryComponent entry : results.getEntry()) {
Observation obs = (Observation) entry.getResource();
System.out.println("Found: " + obs.getId());
}
// Lấy trang tiếp theo khi cần
if (results.getLink(Bundle.LINK_NEXT) != null) {
Bundle nextPage = client.loadPage().next(results).execute();
// Xử lý trang tiếp theo
}
// Hoặc duyệt qua tất cả các trang một cách tự động
Bundle firstPage = results;
do {
// Xử lý trang hiện tại
for (BundleEntryComponent entry : firstPage.getEntry()) {
// Xử lý mỗi resource
}
// Lấy trang tiếp theo nếu có
if (firstPage.getLink(Bundle.LINK_NEXT) != null) {
firstPage = client.loadPage().next(firstPage).execute();
} else {
firstPage = null;
}
} while (firstPage != null);6. Xử lý lỗi và exception handling
Thư viện cung cấp cơ chế xử lý lỗi toàn diện, giúp bạn xử lý các tình huống khác nhau:
try {
// Thực hiện thao tác với FHIR server
Patient patient = client.read()
.resource(Patient.class)
.withId("non-existent-id")
.execute();
} catch (ResourceNotFoundException e) {
// Xử lý khi resource không tồn tại
System.out.println("Patient not found: " + e.getMessage());
} catch (AuthenticationException e) {
// Xử lý lỗi xác thực
System.out.println("Authentication failed: " + e.getMessage());
} catch (BaseServerResponseException e) {
// Xử lý các lỗi server khác
int statusCode = e.getStatusCode();
String responseBody = e.getResponseBody();
System.out.println("Server error " + statusCode + ": " + responseBody);
// Trích xuất OperationOutcome nếu có
if (e.getOperationOutcome() != null) {
OperationOutcome outcome = (OperationOutcome) e.getOperationOutcome();
// Xử lý chi tiết lỗi
}
}7. Hỗ trợ FHIR operations
FHIR định nghĩa nhiều operations đặc biệt như $everything, $validate, $meta, và hapi-fhir-client hỗ trợ gọi các operations này:
// $everything operation - lấy tất cả dữ liệu của bệnh nhân
Bundle everything = client.operation()
.onInstance(new IdType("Patient", "123"))
.named("$everything")
.withNoParameters(Parameters.class)
.returnResourceType(Bundle.class)
.execute();
// $validate operation - kiểm tra resource
Parameters inParams = new Parameters();
inParams.addParameter().setName("resource").setResource(patient);
Parameters outParams = client.operation()
.onType(Patient.class)
.named("$validate")
.withParameters(inParams)
.execute();
// Custom operation với parameters
Parameters matchParams = new Parameters();
matchParams.addParameter().setName("targetSystem").setValue(new StringType("http://loinc.org"));
matchParams.addParameter().setName("code").setValue(new StringType("8480-6"));
Parameters results = client.operation()
.onType(CodeSystem.class)
.named("$lookup")
.withParameters(matchParams)
.execute();Ví dụ thực tế
Ứng dụng tìm kiếm và hiển thị bệnh nhân
import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.rest.client.api.IGenericClient;
import ca.uhn.fhir.rest.gclient.ReferenceClientParam;
import org.hl7.fhir.r5.model.*;
public class PatientSearchExample {
public static void main(String[] args) {
// Khởi tạo client
FhirContext ctx = FhirContext.forR5();
IGenericClient client = ctx.newRestfulGenericClient("http://hapi.fhir.org/baseR5");
// Tìm kiếm bệnh nhân có họ bắt đầu bằng "N"
Bundle patientBundle = client.search()
.forResource(Patient.class)
.where(Patient.FAMILY.matches().value("N"))
.returnBundle(Bundle.class)
.execute();
System.out.println("Found " + patientBundle.getTotal() + " patients");
// Hiển thị thông tin bệnh nhân đầu tiên
if (!patientBundle.getEntry().isEmpty()) {
Patient firstPatient = (Patient) patientBundle.getEntryFirstRep().getResource();
System.out.println("\nPatient Details:");
System.out.println("ID: " + firstPatient.getIdElement().getIdPart());
if (firstPatient.hasName()) {
HumanName name = firstPatient.getNameFirstRep();
System.out.println("Name: " + name.getNameAsSingleString());
}
if (firstPatient.hasBirthDate()) {
System.out.println("Birth Date: " + firstPatient.getBirthDate());
}
if (firstPatient.hasGender()) {
System.out.println("Gender: " + firstPatient.getGender().getDisplay());
}
// Tìm các Observations của bệnh nhân này
Bundle obsBundle = client.search()
.forResource(Observation.class)
.where(new ReferenceClientParam("subject").hasId(firstPatient.getIdElement()))
.returnBundle(Bundle.class)
.execute();
System.out.println("\nObservations for this patient: " + obsBundle.getTotal());
for (Bundle.BundleEntryComponent entry : obsBundle.getEntry()) {
Observation obs = (Observation) entry.getResource();
System.out.println("\n - Observation ID: " + obs.getIdElement().getIdPart());
if (obs.hasCode() && obs.getCode().hasCoding()) {
Coding coding = obs.getCode().getCodingFirstRep();
System.out.println(" Type: " + coding.getDisplay() + " (" + coding.getCode() + ")");
}
if (obs.hasValue()) {
if (obs.getValue() instanceof Quantity) {
Quantity quantity = (Quantity) obs.getValue();
System.out.println(" Value: " + quantity.getValue() + " " + quantity.getUnit());
} else {
System.out.println(" Value: " + obs.getValue().toString());
}
}
if (obs.hasEffective()) {
System.out.println(" Date: " + obs.getEffectiveDateTimeType().getValueAsString());
}
}
}
}
}Tạo và cập nhật nhiều resources trong một transaction
import ca.uhn.fhir.context.FhirContext;
import ca.uhn.fhir.rest.client.api.IGenericClient;
import org.hl7.fhir.r5.model.*;
import java.util.Date;
import java.util.UUID;
public class TransactionExample {
public static void main(String[] args) {
FhirContext ctx = FhirContext.forR5();
IGenericClient client = ctx.newRestfulGenericClient("http://hapi.fhir.org/baseR5");
// Tạo bệnh nhân mới
Patient patient = new Patient();
patient.addName().setFamily("Trần").addGiven("Minh");
patient.setBirthDate(new Date());
patient.setGender(Enumerations.AdministrativeGender.MALE);
// Tạo observation mới cho bệnh nhân
Observation observation = new Observation();
observation.setStatus(Observation.ObservationStatus.FINAL);
observation.getCode().addCoding()
.setSystem("http://loinc.org")
.setCode("8480-6")
.setDisplay("Systolic blood pressure");
// Sử dụng UUID tạm thời để liên kết resources trong bundle
String patientUuid = UUID.randomUUID().toString();
// Set reference từ observation đến patient
observation.setSubject(new Reference("urn:uuid:" + patientUuid));
// Đặt giá trị cho observation
Quantity quantity = new Quantity();
quantity.setValue(120);
quantity.setUnit("mmHg");
quantity.setSystem("http://unitsofmeasure.org");
quantity.setCode("mm[Hg]");
observation.setValue(quantity);
// Tạo bundle theo kiểu transaction
Bundle bundle = new Bundle();
bundle.setType(Bundle.BundleType.TRANSACTION);
// Thêm patient vào bundle
bundle.addEntry()
.setFullUrl("urn:uuid:" + patientUuid)
.setResource(patient)
.getRequest()
.setMethod(Bundle.HTTPVerb.POST)
.setUrl("Patient");
// Thêm observation vào bundle
bundle.addEntry()
.setResource(observation)
.getRequest()
.setMethod(Bundle.HTTPVerb.POST)
.setUrl("Observation");
// Gửi transaction đến server
Bundle responseBundle = client.transaction().withBundle(bundle).execute();
// Xử lý kết quả
System.out.println("Transaction completed with " + responseBundle.getEntry().size() + " entries");
for (Bundle.BundleEntryComponent entry : responseBundle.getEntry()) {
System.out.println("Created: " + entry.getResponse().getLocation());
}
}
}Cài đặt và cấu hình
Thêm thư viện vào dự án Maven:
<dependency>
<groupId>ca.uhn.hapi.fhir</groupId>
<artifactId>hapi-fhir-base</artifactId>
<version>6.4.0</version>
</dependency>
<dependency>
<groupId>ca.uhn.hapi.fhir</groupId>
<artifactId>hapi-fhir-client</artifactId>
<version>6.4.0</version>
</dependency>
<dependency>
<groupId>ca.uhn.hapi.fhir</groupId>
<artifactId>hapi-fhir-structures-r5</artifactId>
<version>6.4.0</version>
</dependency>Thêm vào Gradle Project:
implementation 'ca.uhn.hapi.fhir:hapi-fhir-base:6.4.0'
implementation 'ca.uhn.hapi.fhir:hapi-fhir-client:6.4.0'
implementation 'ca.uhn.hapi.fhir:hapi-fhir-structures-r5:6.4.0'Tùy chỉnh client
HAPI FHIR Client cung cấp nhiều tùy chọn để điều chỉnh hành vi của client:
// Tạo context
FhirContext ctx = FhirContext.forR5();
// Tùy chỉnh client factory
IRestfulClientFactory factory = ctx.getRestfulClientFactory();
// Thiết lập timeout
factory.setConnectTimeout(20000); // 20 giây cho kết nối
factory.setSocketTimeout(40000); // 40 giây cho socket
// Thiết lập proxy nếu cần
factory.setProxy("proxy.example.com", 8080);
// Thiết lập HTTP client
factory.setHttpClient(customHttpClient);
// Tạo client với factory đã tùy chỉnh
IGenericClient client = ctx.newRestfulGenericClient("http://hapi.fhir.org/baseR5");
// Thêm interceptors
client.registerInterceptor(new LoggingInterceptor(true)); // Ghi log request/response
// Thêm interceptor tùy chỉnh để xử lý authentication
client.registerInterceptor(new IClientInterceptor() {
@Override
public void interceptRequest(IHttpRequest request) {
request.addHeader("Authorization", "Bearer " + getAccessToken());
}
@Override
public void interceptResponse(IHttpResponse response) {
// Xử lý response nếu cần
}
});Kết luận
Thư viện hapi-fhir-client cung cấp một API mạnh mẽ và linh hoạt để tương tác với FHIR servers. Với thiết kế fluent interface trực quan, hỗ trợ đầy đủ các hoạt động RESTful, và các tính năng xử lý nâng cao như transactions và phân trang, thư viện này làm cho việc tích hợp với các hệ thống y tế dựa trên FHIR trở nên đơn giản và hiệu quả.
Đối với các nhà phát triển đang xây dựng ứng dụng y tế hiện đại, hapi-fhir-client là một công cụ thiết yếu trong bộ công cụ phát triển, giúp kết nối liền mạch với hệ sinh thái FHIR ngày càng phổ biến.
Last updated