REST/platform 4.8.2 ile cache ve Dubbo 0.9.2 kullanın. Tekrarlanan yanıt tamponu büyümeleri azalır. Kullanılmayan JSON header haritası oluşturulmaz. Java iş kodu, varsayılanlar ve ABI değerleri değişmez. Geçiş ayrıntıları.
REST/platform 4.8.2 ile bir @Configuration sınıfında
sınırlı admission bean'ini tanımlayın; üretilmiş RPC istemcisini handler'a enjekte edin:
@Bean
public LongKeyAdmission customerCommandKeyAdmission() {
return new LongKeyAdmission(true, 1, 256);
}@PostMapping("/customers/{customerId}/refresh")
@KeyAdmission(bean = "customerCommandKeyAdmission", key = "customerId")
public CompletionStage<NativeResponseHandle> refresh(@PathVariable("customerId") long customerId) {
return client.refreshNativeJsonAsync(customerId);
}Tipler com.reactor.rust.annotations.KeyAdmission, com.reactor.rust.concurrent.LongKeyAdmission
ve com.reactor.rust.dubbo.NativeResponseHandle paketlerindedir. Native JSON taşıyıcısının adı
NativeResponseHandle'dır; NativeJsonHandle değildir. APT, adı verilen bean'i başlangıçta bağlar
ve doğrudan çağırır. Genel generated-invoker zorunluluğu kapalı olsa da bu rotanın üretilmiş invoker'ı
zorunludur. Üretilmiş kayıt veya doğru tip/adla bean yoksa başlangıç durur. Anahtar, doğrudan bir
@PathVariable ya da @RequestParam ile bağlanan long veya String olmalıdır. String hash'i
kararlıdır; aynı stripe'a düşen anahtarlar kapasiteyi paylaşır. Bekleme kuyruğu ve bu sıcak yolda
reflection yoktur. Kapasite dolunca standart hata eşlemesi HTTP 503 (service_unavailable) döndürür.
İzin, HTTP isteği iptal edilene kadar değil, kaynak stage tamamlanana kadar tutulur.
Mevcut ret yanıtınızı korumak için @KeyAdmission içine onRejected = "refreshRejected" ekleyin.
Bu metot public olmalı, static olmamalı ve tek bir Throwable parametresi almalıdır.
Dönüş tipi handler ile uyumlu olmalıdır. Asenkron handler için hata yanıtını tamamlanmış bir stage
içinde döndürün. APT imzayı kontrol eder ve doğrudan metot çağrısı üretir. Bu seçenek yalnız kabul
kontrolünün reddini eşler. RPC hatalarını gizlemez ve mevcut hata işleme kodunu değiştirmez.
Örnek consumer, eski hata kodlarını korumak için bu seçeneği kullanır.
APT; doğrudan NativeResponseHandle, ResponseEntity<NativeResponseHandle> ve bunların
CompletionStage/CompletableFuture biçimlerini isteğe bağlı DubboResponses.reply/replyAsync
ile uyarlar. Elle nativeId() çıkarmak gerekmez. Açık ResponseEntity durum/başlıkları korunur.
Elle adaptasyon için Dubbo sahiplik rehberine bakın.
HTTP iptali kaynak RPC'yi iptal etmez; sınırlı RPC deadline'ı sürer ve geç gelen owner kapatılır.
Buffer yeniden yazımı aynı sonucu kullanır; yanıt byte'larını cache'lemez veya iş çağrısını tekrarlamaz.
Açıkça seçilen statik yanıt/cache API'leri ayrıdır.
K-001: Birincil köprü JNI'dır. REST ABI 29 ve Dubbo ABI 7 imzaları değişmez. Ek temizleme
export'ları eşleşen 4.8.2 native paketindedir. Java ve native kaynakları birlikte güncelleyin.
Yalnız Java'yı güncellemek, elle seçilmiş native dosyayı güncellemez.
JNI worker, son senkron handler'ın yanıt boyutunu hatırlar. Aynı handler'a gelen gövdesiz istekte, Java çağrısından önce uygun boyutlu bir çıkış buffer'ı seçebilir. Hatırlanan boyut en fazla 16 KiB'dir. Farklı boyut grubunda sıfırlanır. Async çağrı bu bilgiyi kullanmaz ve değiştirmez. Kuyruktaki istekler mevcut 4 KiB başlangıç buffer'ını kullanır. Yanıt içeriği, istek parametreleri ve iş sonucu cache'lenmez. Handler kodu, yanıt sınırları, rota kabul kontrolü ve JNI sözleşmesi değişmez.
Bu iyileştirme için eşleşen 4.8.2 native runtime kullanın. Eski pakete yeni SO/DLL kopyalamayın. Rota veya RPC kuyruğu dolduğunda uygulanan kapasite korumasını
ve overload yanıtlarını kaldırmaz.
Hazır JSON verisi için RawResponse.json(bytes) kullanmaya devam edin. Yanıt,
değiştirilebilir header haritasını yalnız kodunuz header'ları okur veya değiştirirse
oluşturur. Yeni ayar veya handler değişikliği gerekmez. UTF-8, özel header'lar ve
yanıta ait kodlanmış byte dizisi aynı şekilde çalışır. Yanıt içeriği cache'lenmez.
EmaTech karşılaştırmasında cache detail ve segment okumaları, 16 ve 64 eşzamanlı
istekte mevcut RPS, p99 ve tepe RSS sınırlarını geçti. Ölçülen isteklerde hata yoktu.
Bu sonuç, her uygulamada hızlanma garantisi veya uzun süreli yük testi sonucu değildir.
Bu iyileştirme 4.8.2 paketindedir. Ölçüm kapsamı sürüm kanıtlarında belirtilir.
İsteğe bağlı native edge politikaları, JWT güvenliği, W3C izleme başlıkları, üretilmiş çağrı kodu ve sınırlı native JSON görünümleri eklendi. Handler ve iş kuralları Java'da kalır. OpenJ9 JNI kullanır. FFM ayrı bir seçenektir.
Kullanım rehberi · Sürüm notları
Somut özellik/sample haritası ve okuma maliyetleri.
Yeni kullanım rehberi: Açık ve sınırlı işlemler.
Native uyumluluk: Native platformlar ve başlangıç uyumluluğu. 4.8.0 koordineli yayımında Linux OpenJ9 işlev kanıtı ile diğer platformların derleme/kaynak kanıtı ayrıdır; bağlı rehberlerdeki eski snapshot'lar tarihseldir.
İsteğe bağlı 4.8.0 özelliği: Geçersiz HS256 token'ını Rust'ta reddetme; Java yetki kontrolünü koruma. Açık anahtarla JWT ve sınırlı token önbelleği: RS256, ES256 ve Ed25519 rehberi. Bu JCA yolu native HS256'dan ayrıdır. Mevcut kimlik doğrulama varsayılanları değişmez. Dış HTTP çağrıları ve üretilmiş circuit breaker için sınırlı istemci rehberini kullanın. W3C izleme ve retry başlık koruması için isteğe bağlı tracing rehberini kullanın. Yeni buffer codec'i ve parent ID değişiklikleri 4.8.0 yayımına dahildir.
İsteğe bağlı Java 21 FFM: Ham Redis JSON verisini shared slab ile okuma. Bu ayrı yayımlanan isteğe bağlı Java modülü varsayılan JNI okuyucusunu, sürümlü snapshot'ı veya Java handler'ını değiştirmez.
İsteğe bağlı özellik: Native veri görünümü ve isteğe bağlı toplu JSON yazımı.
İsteğe bağlı özellik: Üretilmiş switch dispatch ve derleme uyumluluğu.
Bu eklemeler 4.8.0 ile yayımlanmıştır. Native view ve SWAR açıkça seçilir.
Üretilmiş dispatch derlemede varsayılan olarak auto kullanır; önceki adapter'lar
için legacy seçin. HTTP sözleşmesi ve native ABI değişmez.
İsteğe bağlı owned JSON yolu: cache entegrasyonu, CacheReadSnapshot sahibini
CacheResponses.ownedJson(...) yardımcısına devredebilir. L1 hit'inde JSON, Java payload
dizisi oluşmadan sabit alandan native yanıt buffer'ına yazılır. Buffer küçükse aynı
sahip korunur. Yazım bitince, hata oluşunca veya işlem iptal edilince kaynak bırakılır.
Mevcut DTO, RawResponse ve normal JsonBodyProducer API'leri değişmez. Alt katmandaki
işaretleyici ManagedJsonBodyProducer olur; uygulama genelde cache yardımcısını kullanır.
Tipli Dubbo listesini değiştirmeden HTTP JSON yanıtı olarak iletecekseniz isteğe
bağlı java-rust-dubbo-rest-adapter kaynak modülünü kullanabilirsiniz.
DubboJsonResponses.body(result), consumer satır DTO'larını oluşturmadan native
Hessian verisini JSON'a yazar. Handler ve iş kararları Java'da kalır. Kurucu
doğrulaması, sıralama veya alan değiştirme gerekiyorsa normal DTO yolunu seçin.
Bu yol sınırlı buffer'a yazar; sınırsız chunked streaming değildir. Sample'daki
direct-json-consumer profili tam akışı gösterir. Spring Dubbo 0.8.1 modüllerini kullanın.
Bu API için eşleşen REST 4.8.2 / cache 0.9.2 paketlerini kullanın.
Sample L1 rehberine bakın.
4.8.0 buffer düzeltmesi: eşleşen Java ve native sürümleri, yanıt buffer'ı küçük
kaldığında mevcut sonucu yeniden yazar. RawResponse, DTO veya ResponseEntity döndüren handler
yeniden çağrılmaz. Bu bir yanıt cache'i değildir. Sonuç, yazım bitince veya işlem iptal edilince
bırakılır. Ek payload kopyası veya daha büyük bir global kuyruk oluşturulmaz. Eski Java/native
eşleşmeleri çalışmaya devam eder. Düzeltmeden yararlanmak için iki taraf da güncellenmelidir.
Buffer'a yazıp int döndüren doğrudan handler, mevcut boyut bildirme kuralını kullanır ve yeniden
çağrılabilir. JsonBodyProducer.write da daha büyük buffer ile yeniden çalışabilir. Bu yazım
metotları aynı veriyi tekrar yazabilmelidir. Veri tabanı veya RPC çağrısını handler'da yapın.
Writer yalnız daha önce alınan veriyi yazsın.
4.8.0 async kaynak yönetimi: HTTP zaman aşımının ve bekleyen
istek kaydının tek sahibi Rust olur. Java yalnız future sonucunu iletir. İkinci
bir zamanlayıcı veya istek tablosu kurmaz. HTTP zaman aşımından sonra gelen
sonuç da native temizleme yoluna ulaşır; Java yanıt buffer'ı havuza döner.
Handler'ınızı veya reactor.rust.async.response-timeout-ms ayarını değiştirmeniz
gerekmez. Bu süre HTTP isteğini bitirir; iş kodunuzu kesmez. Veri tabanı ve RPC
çağrılarına ayrıca sınırlı timeout verin. Bu düzeltme tek başına ölçülmüş bir
performans kazancı anlamına gelmez.
Aynı kaynakta async rota, Java işi bitip hazır yanıt mevcut
reactor.rust.http.max-inflight-response-bytes bütçesinden pay aldığında çalışma
kotasını bırakır. Hazır yanıt için HTTP motorunun yeniden çalışmasını beklemez.
Byte bütçesi alınamazsa eski kota süresi korunur. İptal edilen veya reddedilen
native yanıtın kaynakları da bırakılır. Eşzamanlı iş sınırı, kuyruk kapasitesi ve
timeout büyütülmez. RPC sınırını ve yanıt byte bütçesini ayrı tutun. Yavaş bir
istemci, sınırsız hazır yanıt kuyruğu oluşturmamalıdır.
Güncel kaynakta, ek header içermeyen RawResponse.nativeResponse(id) async
sonucu Rust'a yalnız ID ve durum koduyla geçer. Handler ve future dönüşümleri
yine Java'da çalışır. Bu yol için Java'da byte-array kontrol frame'i hazırlanmaz.
Yanıt byte sınırı ve geç gelen sonucun temizliği Rust'ta korunur. Ek header varsa
mevcut frame yolu kullanılır. Eski ABI-29 native dosya bir kez algılanır ve uyumlu
frame yoluna döner. Tahsisatı azaltan yoldan yararlanmak için güncel native dosya
gerekir; eski binary için aynı performans kazancı vaat edilmez.
İsteğe bağlı kaynak kod: Herkese açık GET rotalarında edge cache ve hız limiti. Native isabette Java guard çalışmaz. Bu nedenle kurulumda açık rota onayı gerekir.
Bu doküman 4.8.2 ve isteğe bağlı agent 0.7.1 hattını anlatır. Yayın için eşleşen performans
kontrolü geçmelidir. Yayımlanan sürümlerden
birini kullanın. Son doğrulama raporları yayına eklenir. Kaynak branch'i yayımlanmış paket değildir.
Core ve platform modüllerini kaynaktan derlemek için v4.8.2 tag'ini kullanın.
İki Maven sürümü de 4.8.2 olur. Native binary'ler yeniden derlenmedi; paketlenen provenance
bilgileri düzeltildi. Gerçek Rust kaynak commit'i manifestte korunur. Platform rehberine bakın.
Rust-Java REST, Java ile REST servisi geliştirmek için hazırlanmış düşük gecikmeli bir framework'tür. İş mantığınız Java'da kalır. Rust Hyper; HTTP bağlantısını, request okuma işlemini, response yazmayı, dosya aktarımını, WebSocket transport'unu ve native backpressure mekanizmasını yönetir.
Temel ayrım nettir:
| Sorumluluk | Çalıştığı taraf |
|---|---|
| Handler, service, component ve business rule | Java |
| Record, validation, veri tabanı ve RPC çağrısı | Java |
| HTTP accept, parse, response write ve file stream | Rust |
| Bounded queue, native buffer ve connection yönetimi | Rust |
| Component graph ve route invoker üretimi | Maven build sırasında Java codegen |
Framework, Spring Boot kopyası değildir. Benzer REST annotation'ları sunar. Ancak daha küçük ve daha öngörülebilir bir runtime yüzeyi hedefler.
Bu framework şu durumda doğru seçimdir: HTTP servisinizin handler, service ve iş kuralları Java'da kalacak; bağlantı, sınırlı I/O ve seçilmiş ağır response yolları Rust tarafından yönetilecektir. Uygulamanız Spring application context, runtime bean discovery veya Spring ekosistemine sıkı bağlı kütüphaneler gerektiriyorsa bu framework doğru başlangıç değildir.
| İhtiyacınız | Açmanız gereken bölüm |
|---|---|
| Hemen yeni servis oluşturmak | Beş Dakikada Başlangıç |
| Çalışan GET, POST, PATCH, DELETE, upload veya WebSocket örneği görmek | Derlenen örnekler |
| Yalnız REST, Dubbo, cache, scheduler veya WebSocket bağımlılığını seçmek | Platform ve starter rehberi |
| Record, direct writer, hazır JSON veya file streaming arasında karar vermek | Response Yolunu Seçin |
| Pod belleği, eşzamanlılık ve endpoint limitlerini ayarlamak | Production runtime rehberi |
| Bir property'nin anlamını bulmak | Konfigürasyon referansı |
Startup, fallback, native yükleme veya 503 sorununu çözmek |
Sorun giderme |
Bu patch; platform parent, BOM, starter ve sample sürümlerini hizalar. Pakette Windows x64,
Linux x64, Linux ARM64 ve macOS ARM64 native dosyaları bulunur. Linux GLIBC alt sınırı 2.17,
macOS ARM64 hedefi 11.0 olarak korunur. ABI numaraları ve Java handler kullanımı değişmez.
Başka sürümden native dosya kopyalamayın. Ayrıntılar sürüm notlarındadır.
4.6.2, collector bağlantı yenilemesi sırasında oluşabilen veri kaybını düzeltir. Exporter CPU izolasyonu korunur. Java iş mantığı ve endpoint davranışı değişmez.
- Windows ve Linux native dosyaları temiz
rust-spring v4.8.0build'inden alınır. - Embedded REST telemetrisi başlangıçta collector erişimini doğrular ve bu bağlantıyı kapatır. Sınırlı h2 bağlantısını yalnız export penceresinde açar. Hyper data plane yanında idle collector bağlantısı tutmaz.
- Ayrı Spring agent, standalone Rust runtime içinde tek sınırlı collector bağlantısını yeniden kullanmaya devam eder.
- Standalone bağlantı 15 dakika sonra yenilenir. Bu süre Glowroot Central'ın 20 dakikalık bağlantı sınırından kısadır. Aggregate sayaçları alınmadan önce bağlantı hazırlık kontrolü yapılır.
- Aggregate payload, Central onay verene kadar tek ve sınırlı pending batch içinde tutulur. Bağlantı kapanırsa exporter yeniden bağlanır ve aynı protobuf byte dizisini tekrar yollar. Retry geçici olarak sonuç vermezse yeni trafik önceden ayrılmış sayaçlarda birikmeye devam eder.
- Tamamlanan her HTTP isteği
Webtransaction type altında tam olarak bir kez sayılır. Route adı HTTP metodunu içermez. Örneğin/orders/{id},/orders/*olarak görünür. - Diagnostic yavaş/hatalı trace; HTTP metodu, response kodu, Spring controller satırı ve süresi, request thread CPU/blocked/waited/allocation sayaçları, iç Dubbo süresi ve sınırlı exception stack bilgisini gösterebilir.
- Ayrı çift yönlü collector bağlantısı Thread dump, OpenJ9 heap histogram/dump, Force GC, MBean tree, System properties ve capability isteklerini destekler. Hyper worker kullanmaz.
- Environment ekranına host, process, Java/OpenJ9, maskelenmiş JVM argümanları, dump dizini ve agent sürümü gönderilir. Kubernetes secret içerebildiği için bütün işletim sistemi environment variable değerleri gönderilmez.
reactor.glowroot.http.sample-rateyalnız isteğe bağlı trace ayrıntısını sınırlar. Endpoint sayısını, latency histogramını, throughput veya hata toplamını azaltmaz.- İzole exporter Linux'ta düşük öncelikli batch işi, Windows'ta en düşük normal thread önceliğiyle çalışır. Hyper executor'ını kullanmaz.
micro,jvm,sql,fullvediagnosticprofilleri çalışma sırasında değiştirilebilir.- Düşük profile dönüldüğünde profile ait kuyruklar, SQL slot'ları, diagnostic state ve JNI referansları kontrol çağrısı tamamlanmadan bırakılır.
- REST ABI
29, Dubbo ABI7, Redis ABI6ve Glowroot ABI6kullanılır. - Native DLL/SO,
4.8.2Maven artifact'i içinde gelen dosya olmalıdır. collector_preflight_reconnects,collector_request_retries,deferred_intervalsvepending_aggregate_transactionsalanları rotasyonun kayıpsız toparlandığını gösterir.
- Beş Dakikada Başlangıç
- En Küçük Starter Setini Seçin
- Platform ve Starter Rehberi
- REST Endpoint Örneği
- Build Sırasında Neler Üretilir?
- Response Yolunu Seçin
- Runtime Profilini Seçin
- Endpoint Kapasitesi ve Kontrollü 503
- Request, Response ve Timeout Sınırları
- Gözlemlenebilirlik
- Startup ve OpenJ9
- Konfigürasyon Önceliği
- Production Kontrol Listesi
- Örnek Projeler
- Sürüm ve Native ABI
Yeni projede platform parent ve yalnız ihtiyacınız olan starter'ı kullanın. Parent; framework, codegen, Maven plugin ve ek kütüphane sürümlerini hizalar. Annotation processor sınıfları derleme yolunda kalır. Production runtime JAR'ına girmez.
<parent>
<groupId>com.reactor</groupId>
<artifactId>rust-java-platform-parent</artifactId>
<version>4.8.2</version>
</parent>
<dependencies>
<dependency>
<groupId>com.reactor</groupId>
<artifactId>rust-java-starter-rest</artifactId>
</dependency>
</dependencies>Application sınıfını oluşturun:
package com.example.catalog;
import com.reactor.rust.annotations.ReactorApplication;
import com.reactor.rust.app.RestApplication;
@ReactorApplication(scanBasePackages = "com.example.catalog")
public final class CatalogApplication {
public static void main(String[] args) {
RestApplication.run(CatalogApplication.class, args);
}
}Bir service ve handler ekleyin:
package com.example.catalog;
import com.reactor.rust.annotations.Response;
import com.reactor.rust.di.annotation.Component;
@Component
final class CatalogService {
CatalogItem find(long id) {
return new CatalogItem(id, "READY");
}
}
@Response
record CatalogItem(long id, String status) {}package com.example.catalog;
import com.reactor.rust.annotations.GetMapping;
import com.reactor.rust.annotations.PathVariable;
import com.reactor.rust.annotations.RestController;
@RestController("/api/v1/catalog")
final class CatalogHandler {
private final CatalogService catalog;
CatalogHandler(CatalogService catalog) {
this.catalog = catalog;
}
@GetMapping("/{id}")
CatalogItem get(@PathVariable("id") long id) {
return catalog.find(id);
}
}Küçük bir property dosyası yeterlidir:
server.host=0.0.0.0
server.port=8080
reactor.runtime.profile=micro-restBuild alın ve çalıştırın:
mvn clean verify
mvn exec:java
curl http://localhost:8080/api/v1/catalog/1scanBasePackages verilmezse application sınıfının paketi kullanılır. Handler ve service sınıfları
kardeş paketlerdeyse ortak paket kökünü yazın.
Her ihtimal için tüm starter'ları eklemeyin. Sürecin yaptığı işe göre seçim yapın.
| Uygulama tipi | Eklenecek starter | Eklenmemesi gereken gereksiz yüzey |
|---|---|---|
| Yalnız REST API | rust-java-starter-rest |
Dubbo, Redis, scheduler ve WebSocket |
| REST + native Dubbo consumer | rust-java-starter-dubbo |
Static discovery kullanırken resmi Dubbo, Netty ve ZooKeeper |
| REST + Redis reader | rust-java-starter-cache-reader |
Redis writer lifecycle'ı |
| PostgreSQL'den Redis'e yazan scheduler | rust-java-starter-cache-writer |
REST runtime |
| WebSocket servisi | rust-java-starter-websocket |
WebSocket kullanmayan servislerde bu starter |
| REST + OpenAPI | rust-java-starter-rest, rust-java-starter-openapi |
Runtime controller taraması |
| REST + JWT | rust-java-starter-rest, rust-java-starter-security |
Her request'te dinamik policy arama |
| REST + dış HTTP çağrısı | rust-java-starter-rest, rust-java-starter-http-client |
Dynamic proxy ve sınırsız executor |
Kapalı bir özellik request yolunda çalışmayabilir. Ancak gereksiz dependency yine classpath'i büyütür. Bu nedenle kullanılmayan starter'ı eklememek en doğru memory optimizasyonudur.
Tüm starter'ların açıklaması için Platform Rehberi dosyasına bakın.
Aşağıdaki örnek temel verb'leri aynı handler içinde gösterir. JSON sözleşmelerinde immutable record kullanın. Validation işini request record üzerinde açıkça tanımlayın.
@Request
public record ProductCommand(
@NotBlank String name,
@Positive long priceCents) {}
public record ProductResponse(long id, String name, long priceCents) {}@RestController("/api/v1/products")
final class ProductHandler {
private final ProductService products;
ProductHandler(ProductService products) {
this.products = products;
}
@GetMapping("/{id}")
ProductResponse get(@PathVariable("id") long id) {
return products.get(id);
}
@GetMapping("")
List<ProductResponse> list(
@RequestParam(value = "limit", defaultValue = "50") int limit) {
return products.list(limit);
}
@PostMapping("")
ResponseEntity<ProductResponse> create(@RequestBody @Valid ProductCommand command) {
return ResponseEntity.created(products.create(command));
}
@PutMapping("/{id}")
ProductResponse replace(
@PathVariable("id") long id,
@RequestBody @Valid ProductCommand command) {
return products.replace(id, command);
}
@PatchMapping("/{id}")
ProductResponse patch(
@PathVariable("id") long id,
@RequestBody @Valid ProductCommand command) {
return products.patch(id, command);
}
@DeleteMapping("/{id}")
ResponseEntity<Void> delete(@PathVariable("id") long id) {
products.delete(id);
return ResponseEntity.noContent();
}
}Business logic handler içinde büyümemelidir. Handler HTTP sözleşmesini yönetir. Service iş kararını uygular. Repository veri tabanı erişimini yönetir.
Normal 200 sonucu için DTO'yu doğrudan döndürmek en küçük yoldur. Status veya header değişecekse
HttpResponse<T> kullanın. Tutarlı hata body için RFC 9457 uyumlu ProblemDetail kullanın.
@Component
final class ApiErrors {
@ExceptionHandler(NotFoundException.class)
HttpResponse<ProblemDetail> notFound(NotFoundException error) {
return HttpResponse.notFound(
ProblemDetail.of(HttpStatus.NOT_FOUND, error.getMessage())
.withCode("catalog_not_found"));
}
}Exception handler'lar indexlenir ve generated kod üzerinden çağrılır. Her route içinde aynı
try/catch kodunu tekrarlamayın. Dependency hata metnini doğrudan client'a açmayın.
Framework, runtime reflection yerine build-time üretimi tercih eder.
| Sizin tanımınız | Üretilen çıktı | Runtime etkisi |
|---|---|---|
@ReactorApplication |
Application descriptor ve startup index | Kontrollü ve doğrudan startup |
| Constructor parametreleri | Bean factory ve dependency graph | Reflective DI araması yok |
| REST annotation'ları | Route'a özel invoker | Reflective method çağrısı yok |
@ConfigurationProperties |
Tip güvenli property binder | Hatalı değer startup'ta reddedilir |
@Response |
Response DTO metadata'sı | Uyumlu DSL-JSON serialization; kendiliğinden writer üretmez |
@GenerateDirectJsonWriter |
Zorunlu tipe özel JSON writer | Trafik başlamadan bir kez bağlanır; desteklenmeyen yapı build hatası verir |
@GenerateJdbcMapper |
Doğrudan ResultSet mapper |
Runtime record incelemesi yok |
@ReactorHttpClient |
Typed HTTP client | Dynamic proxy yok |
@Scheduled |
Bounded task kaydı | Scheduler lifecycle framework tarafından kapatılır |
@RequiresProperty ve @Profile |
Koşullu bean ve route planı | Koşul her request'te değil, startup'ta değerlendirilir |
Platform parent, mvn clean verify sırasında AOT ve native ABI gate'lerini çalıştırır. Generated
dosyalar target/generated-sources/annotations ve target/classes/META-INF/reactor altında bulunur.
Bu dosyaları elle yazmayın.
Compatibility scanning yalnız eski projelerin geçişi içindir. Yeni production uygulamasında strict AOT yolunu kullanın. Fallback tüm çağrıların sessizce yavaş yola düşmesine izin vermemelidir.
Framework metrics ve diagnostics endpoint'leri isteğe bağlıdır. Bu endpoint'lere ihtiyacınız varsa application annotation'ında açın:
@ReactorApplication(
scanBasePackages = "com.example.catalog",
metrics = true)
public final class CatalogApplication { /* main metodu değişmez */ }Varsayılan değer metrics = false olur. Bu durumda metrics handler ve diagnostics route'ları
kaydedilmez. Küçük REST servisi kullanılmayan bir gözlem yüzeyini memory içinde taşımaz.
GET /diagnostics/routes çıktısında generated_route_metadata=true, route bilgisinin build sırasında
üretildiğini gösterir. generated_response_writer=true, route'un doğrudan writer'ı bağladığını
gösterir. Önceden kayıtlı writer route planı hazırlanırken bağlanır. Sonradan kaydedilen writer için
ilk null olmayan object response sırasında yalnız bir kez daha arama yapılır. Producer, raw, native
ve file route'ları writer araması yapmaz.
generated_response_writer_state alanını şöyle okuyun:
unresolved: Route planı hazırlanırken writer bulunamadı. İlk normal object response sırasında son bir arama yapılır.bound: Tipe özel generated writer bağlandı ve kullanılıyor.miss: Bildirilen response tipi için writer bulunamadı. Bu durumda üst seviyedekidirect_json_writer_enabledvedirect_json_writer_providersalanlarını kontrol edin.disabled: Direct writer desteği konfigürasyon ile kapatıldı.not_applicable: Primitive, producer, raw, native veya file route bu writer'a ihtiyaç duymaz.
Production'da startup reflection istemiyorsanız diagnostics temizlendikten sonra şu gate'i açın:
reactor.optimizer.fail-on-reflection-route-metadata=trueResponse tipi yalnız kod stili değildir. Allocation, JNI copy ve RSS davranışını değiştirir.
| Veri biçimi | Seçim | Ne zaman kullanılır? | Maliyet |
|---|---|---|---|
| Küçük dinamik JSON | Record veya ResponseEntity<Record> |
Normal business API | En sade yol; küçük object graph kabul edilir |
| Scalar ve sık kullanılan record | @GenerateDirectJsonWriter |
Aynı tip yoğun serialize ediliyorsa | Build-time writer; daha az reflection ve ara buffer |
| Büyük dinamik JSON | JsonProducerResponse |
Büyük liste üretilecekse | DTO listesi kurmadan native buffer'a yazar |
| JSON zaten hazır | RawResponse |
Redis, DB veya provider hazır JSON veriyorsa | Tekrar serialize etmez |
| Değişmeyen response | @NativeStaticRoute |
Health, metadata veya sabit sözlük | Java handler'a girmeden Rust dönebilir |
| Büyük dosya | FileResponse |
CSV, rapor veya indirme | Dosya Java heap'e alınmaz |
| Native provider JSON'u | Native response handle | Dubbo/cache body yalnız iletilecekse | Java byte[] materialization kaldırılabilir |
RawResponse genel amaçlı bir cache değildir. Yalnız elinizde hazır body varsa kullanılır.
NativeStaticRoute ise restart'a kadar değişmeyen bilinçli bir response içindir.
Önce en küçük uygun profille başlayın. Yalnız ölçüm sonucu limit değiştirin.
| Profil | Uygun kullanım | Beklenen davranış |
|---|---|---|
micro-rest |
Küçük pod, düşük veya orta trafik | Az worker ve küçük pool; overload durumunda kontrollü 503 olabilir |
micro-rest-plus |
Ağır producer/direct JSON ve daha yüksek eşzamanlılık | Daha geniş route bütçesi; RSS artışı ölçülmelidir |
micro-dubbo |
Memory öncelikli Dubbo consumer | Az bağlantı ve worker; burst yükte fail-fast davranır |
balanced |
Sürekli orta-yüksek trafik | Latency, başarı oranı ve memory arasında denge |
throughput |
RPS öncelikli servis | Daha fazla thread, queue ve retained memory |
p99, isteklerin yüzde 99'unun tamamlandığı gecikme sınırıdır. 503, servis kapasitesi dolduğunda
isteğin kontrollü biçimde reddedildiğini gösterir. Sınırsız queue kullanmak 503 sayısını gizleyebilir;
ancak p99 değerini ve memory kullanımını kötüleştirir.
Profil seçimi performans garantisi değildir. Kendi endpoint karışımınızla en az c64 ve c256 yükte
RPS, p99, 503 oranı ve container RSS ölçün. Ağır route için global worker artırmak yerine
@RouteAdmission veya workload bazlı route budget kullanın.
Anon belleği daha düşük bir container image gerekiyorsa Maven runtime-image goal ile 8m
ROM-only OpenJ9 shared cache üretebilirsiniz. Bu cache AOT metodu tutmaz. Java business logic ve JIT
akışı değişmez. Bu bir runtime profili değil, image seçimidir. Güncel minimal ölçümde final cgroup
anon 31,027 MiB değerinden 28,207 MiB değerine düştü. Uzun c64 small-route gate'inde useful RPS
%11,43 arttı, p99 %35,18 düştü ve hata oluşmadı. Yine de kendi endpoint karışımınızla c64/c256
testi yapmadan açmayın. Copy-paste Maven ayarı
Production Runtime rehberinde bulunur.
Üretilen çok aşamalı imajda binutils yalnız build katmanında kalır. Uygulama 10001 kullanıcısıyla
çalışır. Runtime yazma alanı /app/.reactor/native ve /app/work dizinleriyle sınırlandırılır.
Pahalı bir endpoint'in bütün pod'u yavaşlatmasına izin vermeyin. @RouteAdmission, aynı anda çalışan
çağrı sayısını ve kısa bekleme süresini endpoint üzerinde sınırlar:
@GetMapping(value = "/reports/daily", responseType = JsonBodyProducer.class)
@RouteWorkload(value = RouteWorkload.Type.HEAVY_JSON, budget = "daily-report")
@RouteAdmission(maxConcurrent = 80, queueTimeoutMs = 150)
JsonBodyProducer dailyReport() {
return reportService::writeDailyJson;
}Bu limit dolduğunda sınırsız queue büyütmek yerine kontrollü 503 dönebilir. 503, framework'ün
bozulduğu anlamına gelmez. Pod'un bellek ve gecikme sınırını koruduğunu gösterir. Değeri artırmadan
önce provider, veritabanı pool'u, response boyutu, useful 200 RPS ve p99 birlikte ölçülmelidir.
Property ile endpoint'e özel override yapılabilir:
reactor.rust.route-admission.get.reports.daily.max-concurrent=80
reactor.rust.route-admission.get.reports.daily.queue-timeout-ms=150Global worker veya queue değerini büyütmek ilk çözüm değildir. Tek ağır endpoint için endpoint'e özel bütçe kullanın.
reactor.rust.http.max-request-body-bytes=1048576
reactor.rust.http.max-response-body-bytes=8388608
reactor.rust.http.max-inflight-body-bytes=33554432
reactor.rust.http.max-inflight-response-bytes=67108864
reactor.rust.http.header-read-timeout-ms=5000
reactor.rust.http.request-body-timeout-ms=10000
reactor.rust.http.idle-timeout-ms=30000- Tek request limitini yükseltirken toplam in-flight byte limitini de kontrol edin.
- Büyük dosya için
byte[]yerineFileResponsekullanın. - Büyük dinamik JSON için
List<DTO>kurmak yerine producer/direct writer yolunu değerlendirin. - Timeout'u yalnız hata kaybolsun diye büyütmeyin. Önce beklemenin DB, RPC, queue veya network kaynaklı olduğunu belirleyin.
4.8.0 sürümü, uyumlu java-rust-glowroot-agent:0.7.1 paketiyle kullanılabilir. Mikro ajan şu
verileri Glowroot Central'a gönderir:
- HTTP route çağrı sayısı, süre dağılımı ve
5xxsayısı; - native Dubbo ve native Redis çağrı süreleri;
- process RSS ve thread sayısı;
- exporter bağlantı, hata, reconnect ve drop sayaçları;
- sınırlandırılmış yavaş ve hatalı HTTP trace örnekleri.
Java agent bytecode weaving yapmaz. Runtime dependency eklemez. Protobuf encode ve plaintext HTTP/2 gönderimi mevcut Rust runtime içinde çalışır. Handler, service, validation ve business logic Java'da aynı şekilde kalır.
Stable 4.8.0 runtime; sınırlı micro, jvm, sql, full ve diagnostic profillerini destekler.
REST ABI 29 ve Glowroot ABI 6 gerekir. Bu Java sınıflarını eski Glowroot ABI DLL/SO ile
kullanmayın.
Trafik gönderdikten sonra bir export aralığı bekleyin. Transactions ekranında transaction type
olarak Web seçin. /orders/{id} route'u /orders/* adıyla görünür. Aynı tam istek sayıları
Average, Percentile, Throughput ve Errors ekranlarını besler.
Mevcut Glowroot Central/collector deployment'ı değişmez. İkinci bir collector veya framework'e özel
collector plugin'i kurmayın. Strict düşük-bellek production yolunda agent JAR gerekmez. Native
binary'sinde glowroot capability bulunan uyumlu Rust-Java REST artifact'ini kullanın. Özelliği
-Dreactor.glowroot.*, ortam değişkenleri veya rust-spring.properties ile açın. İsteğe bağlı
-javaagent:/app/agent/java-rust-glowroot-agent.jar yalnız konfigürasyon kolaylığı sağlar ve ayrı
ölçülür. Java controller, handler, service, validation ve iş mantığı değişmez.
Rastgele Java metodunu izlemek, otomatik JDBC weaving, sürekli profiler, uygulama log weaving, request/response body yakalama veya canlı bytecode weaving istiyorsanız tam Glowroot Java agent'ı seçin. Sınırlı runtime; SQL varsa açık SQL sürelerini, sabit JVM/GC ölçümlerini, Spring controller ve Dubbo trace ayrıntısını, sınırlı hata stack bilgisini, MBean erişimini ve yetkili tanılama komutlarını sağlar. Yalnız Dubbo çağıran bir serviste SQL telemetrisi gerekmez.
Agent'ın ağır işleri Rust tarafında kalır. İsteğe bağlı MXBean discovery ve polling, JNI global
referans sahipliği, aggregate işlemleri, kuyruklar, protobuf/h2 gönderimi, tanılama yönetimi, dosya
işlemleri ve profil kaynak iadesi Rust tarafından yürütülür. Java tarafında telemetri polling worker'ı
ve JVM bean cache'i yoktur. Java business kodu yalnız açık SQL süre/hata olayını ve JVM'de oluşan
Throwable referansını iletir.
Profili yalnız kimlik doğrulaması olan iç kontrol akışından değiştirin:
GlowrootTelemetry.switchTo(TelemetryProfile.FULL, Duration.ofSeconds(5));
// Olay inceleme aralığını sınırlı tutun.
GlowrootTelemetry.restoreConfiguredProfile();restoreConfiguredProfile(), reactor.glowroot.profile ile seçilen başlangıç değerine döner. Bu
değer micro ise profile ait SQL slotları, hata ve tanılama kuyrukları, devam eden export verisi ve
Rust'ın sahip olduğu JNI MXBean global referansları bırakılana kadar bekler. Eski SQL tanımları nesil
kontrollüdür. Profil yeniden açıldığında yeni slot kaydı yapar. Profili her request için değiştirmeyin.
Kaynak bırakma worker'ı Hyper'dan ayrıdır. Linux tarafındaki son malloc_trim(0) çağrısı yine de
process genelinde çalışan bir glibc işlemidir. Profil değişimini seyrek bir operasyon adımı olarak
kullanın. RSS etkisini telemetri kapalı/açık taze process A/B testiyle ölçün.
@ReactorApplication(metrics = true) açıksa lokal durumu şu endpoint'lerden okuyabilirsiniz:
curl -s http://localhost:8080/diagnostics/glowroot
curl -s http://localhost:8080/metrics | grep reactor_glowrootJVM ölçümü veya tanılama içermeyen profile döndükten sonra jvm_probe_registered=false ve
jvm_probe_owned_global_refs=0 değerlerini doğrulayın. Bu iki alan, Rust'ın sahip olduğu JNI bean
referanslarının bırakıldığını kanıtlar. Yalnız RSS değerinin düşmesi yeterli kanıt değildir.
Collector, HTTP request kritik yolunda beklenmez. Bağlantı kesilirse sınırlı reconnect backoff
çalışır. Süresi geçen rollup bellekte biriktirilmez; drop edilir ve sayaçta görünür. Uygulama servis
vermeye devam eder. Kaynak kodla uygulanan agent-owned üst sınır 1 MiB değeridir. Önceki
4.4.1 kanıtı shared-runtime yolunu ölçtü. Resident maksimum farkları +1,742 MiB, +1,817 MiB
ve +1,754 MiB oldu; telemetri thread'i eklenmedi. 4.8.0, export ve profil kaynak bırakma işini
tek 256 KiB Rust thread üzerinde izole eder. Hyper worker kullanmaz. Embedded REST başlangıç
collector bağlantısını kapatır ve yalnız sınırlı export penceresinde yeniden bağlanır. Koordineli
release gate'i, companion agent yayınlanmadan önce +3 MiB, RPS, p99 ve 503 sözleşmesini ölçer.
Uygulamada metrics özelliğini yalnız ihtiyaç varsa açın:
@ReactorApplication(
scanBasePackages = "com.example.catalog",
metrics = true)
public final class CatalogApplication { }| Endpoint veya metrik | Ne gösterir? |
|---|---|
GET /metrics |
Prometheus metrikleri |
GET /diagnostics/startup |
Startup aşamaları ve süreleri |
GET /diagnostics/routes |
Generated, direct, native veya fallback route durumu |
| JNI queue p95/p99 | Java handler kuyruğundaki bekleme |
| Route admission rejection | Endpoint kapasite limitine takılan istek |
| In-flight response bytes | Aynı anda taşınan response belleği |
Production gate sırasında production_legacy, heavy_json_object_graph ve fallback sayaçlarını
kontrol edin. Benchmark-only route değerlerini gerçek uygulama route'larıyla karıştırmayın.
Build; component graph, route invoker, property metadata ve startup index dosyalarını üretir. Production başlangıcında classpath taraması yerine bu dosyalar kullanılır. Generated dosyaları elle değiştirmeyin.
OpenJ9/Semeru Java 21 düşük bellek için önerilen runtime'dır. micro-rest ile başlayın. JIT code
cache, compilation thread, native trim veya daha küçük stack ayarlarını ancak aynı endpoint setinde
RPS, p99, 503 ve container RSS karşılaştırması geçerse kullanın. Ayrıntılar için
startup tuning ve production runtime
rehberlerine bakın.
Değerler aşağıdaki sırayla uygulanır. Üstteki kaynak alttakini ezer:
- JVM
-D...değerleri ve desteklenen environment variable'lar. reactor.config.fileveyaREACTOR_CONFIG_FILEile verilen dış property dosyaları.- Classpath içindeki
rust-spring.properties. RuntimeProfilePlanile yalnız eksik değerler için verilen uygulama varsayılanları.
Production secret'larını JAR içindeki property dosyasına yazmayın. Kubernetes Secret veya platformun secret yönetimini kullanın. Framework property dosyasının tamamını her projeye kopyalamayın. Yalnız uygulamanızın değiştirdiği değerleri tutun.
Property ve profil ayrıntıları:
mvn clean verifybaşarılı olmalıdır.- AOT component ve route index'leri JAR içinde bulunmalıdır.
- Runtime loglarında scan veya invoker fallback görülmemelidir.
- DLL/SO aynı Maven paketinden gelmelidir. ABI uyuşmazlığı startup'ı durdurmalıdır.
- Liveness yalnız process durumunu kontrol etmelidir.
- Readiness gerekli Redis, Dubbo veya DB bağımlılıklarını bounded timeout ile kontrol etmelidir.
- c64 ve c256 yükte RPS, p99,
503, JNI queue wait ve container RSS birlikte ölçülmelidir. - DB, Redis, Dubbo ve outbound HTTP için timeout ile bounded inflight limiti bulunmalıdır.
- Command retry yalnız idempotency anahtarı veya idempotent işlem varsa açılmalıdır.
- Büyük response için DTO listesi yerine producer, raw, file veya native handle yolu değerlendirilmelidir.
- Pod CPU ve memory limitleri gerçek staging yüküyle doğrulanmalıdır.
503 her zaman framework hatası değildir. Çoğu zaman bounded overload davranışıdır. Limiti artırmadan
önce CPU, provider, DB pool, Redis ve RSS kapasitesini birlikte kontrol edin.
| İhtiyaç | Başlangıç projesi |
|---|---|
| En küçük REST endpoint | examples/minimal-rest |
| GET, POST, PUT, PATCH ve DELETE | examples/crud |
| Upload | examples/upload |
| Büyük JSON ve dosya response | examples/streaming |
| WebSocket | examples/websocket |
| Redis'ten hazır JSON okuyan REST API | rest-sample-cache-reader |
| PostgreSQL'den Redis snapshot üreten scheduler | rest-sample-cache-writer |
| Dubbo provider çağıran REST API | rest-sample-dubbo-consumer |
| Plain Java Dubbo provider | rest-sample-dubbo-provider |
sample modülü tam uyumluluk demosudur. Production template değildir. Yeni proje için
starter tabanlı yapı veya scripts/new-reactor-project.ps1 kullanın.
.\scripts\new-reactor-project.ps1 `
-Mode rest `
-Artifact customer-api `
-Output C:\work\customer-api `
-Group com.exampleDesteklenen biçimler: rest, cache-reader, cache-writer, dubbo-static ve dubbo-zookeeper.
Generator dolu bir klasörün üzerine yazmaz.
Uyumlu dependency çizgisi rust-java-rest:4.8.2, java-rust-dubbo:0.9.2 ve
java-rust-cache:0.9.2 şeklindedir. Native artifact'ler REST ABI 29, Dubbo ABI 7, Redis ABI 6
ve Glowroot ABI 6 taşır.
Native DLL/SO dosyasını başka bir sürümden kopyalamayın. Startup; ABI, platform, source revision ve SHA-256 provenance bilgisini doğrular. Uyumsuz binary trafik başlamadan reddedilir.
Java tarafındaki handler, service, record ve annotation modeli korunur. Native ABI değişikliği Java business logic kullanımını değiştirmez. Yalnız runtime ve native binary aynı paket çizgisinde olmalıdır.
Native yükleyici ve build iş akışı şu dosya yollarını destekler:
| Platform | REST resource yolu |
|---|---|
| Linux ARM64 | native/linux-arm64/librust_hyper.so |
| macOS ARM64 | native/macos-arm64/librust_hyper.dylib |
ARM64 Java 21 kullanın. macOS build hedefi 11.0, Linux GLIBC alt sınırı 2.17 olarak ayarlanır.
Binary, hedef işlemci için üretilmeli ve SHA-256 provenance bilgisiyle paketlenmelidir.
4.8.2 paketi dört platformu ve SHA-256 provenance bilgilerini içerir.
OpenJ9 21 çalıştırma kontrolleri Windows x64, Linux ARM64 ve macOS ARM64 üzerinde
geçti. Her platformda 20 kontrol çalıştı; atlanan test olmadı. Linux x64 yük ve
uzun süreli çalışma testleri EmaTech'te yapılır. Uyumluluk sonucu ARM/Windows
performans onayı anlamına gelmez.
Native paketleme adımlarını izleyin.
Framework ve sample repoları aynı çalışma dizinindeyse bu repo içinde parent sürümlerini kontrol edin:
.\scripts\verify-version-alignment.ps1Betik platform/parent/pom.xml sürümünü okur. Platform parent kullanan tüm sample projelerini
karşılaştırır. Uyuşmazlıkta çıkış kodu 1 olur.
- Deklaratif geliştirme
- Platform ve starter seçimi
- Konfigürasyon
- Operasyon
- Sorun giderme
- Compile edilmiş örnekler
- Production runtime ve performans kararları
- 4.8.2 sürüm notları
- 4.6.2 sürüm notları
- 4.6.0 sürüm notları
- 4.4.1 sürüm notları
| Terim | Basit anlamı |
|---|---|
| RSS | Uygulamanın işletim sistemi tarafından görülen fiziksel bellek kullanımı |
| p99 | İsteklerin yüzde 99'unun tamamlandığı gecikme sınırı |
Useful 200 RPS |
Saniyede tamamlanan başarılı HTTP 200 response sayısı |
503 |
Kapasite sınırı nedeniyle geçici olarak işlenemeyen istek |
| In-flight | Henüz tamamlanmamış ve kaynak tutan istek veya response |
| Route admission | Bir endpoint'in aynı anda kullanabileceği kapasite sınırı |
| Native response | Body'nin Java heap'e taşınmadan Rust belleğinden gönderilmesi |
| Generated path | Handler çağrısı veya serializer bilgisinin build sırasında üretilmesi |
Business logic Java'da kalır. Rust yalnız düşük seviyeli I/O ve seçilmiş serialization/transport işlerini üstlenir. Bu sınırı korumak framework'ün temel tasarım kararıdır.