DEV Community: Silver_dev

The finale of the Vector Database Showroom series.

Silver_dev — Fri, 09 Oct 2026 19:21:26 +0000

The finale of the Vector Database Showroom series.

Six parts ago, this showroom made you a promise: we won't tell you which database to take — we'll give you a method to figure out what YOU should take. Today the showroom closes: one table, one tree, one checklist.

The roster, for the record: 🚙 pgvector, 🛴 Chroma, 🏎️ Qdrant, 🚐 Weaviate, 🚕 Pinecone, 🚄 Milvus — the station wagon, the scooter, the hatchback, the crossover, the taxi, and the train.

The cost-of-ownership table

Vehicle	License / self-host	Sweet spot	Signature feature	Main pain	Ops burden	Managed by
🚙 pgvector	PostgreSQL license, self-host anywhere	~1M comfortable, ~10M tuned	ACID + joins — vectors live with your data	Vertical ceiling; RAM for the HNSW graph	Your usual Postgres routine	RDS, Aurora, Cloud SQL, AlloyDB, Azure, Supabase, Neon
🛴 Chroma	Apache 2.0, embedded or server	Prototypes; single-digit millions	First search in 90 seconds, embeddings included	Single node by design; prototype-grade durability	None — until it's suddenly too many	Chroma Cloud
🏎️ Qdrant	Apache 2.0, single binary → cluster	Millions → hundreds of millions (quantized)	Filterable HNSW — filters live inside the index	Manual snapshots; a tuning culture	Light-to-medium DevOps	Qdrant Cloud
🚐 Weaviate	BSD-3-Clause, containers	Multi-tenant SaaS; scale via distributed mode	Factory vectorization + built-in BM25F hybrid + native tenancy	A service bay for all those options; the v3/v4 client split	Medium DevOps	Weaviate Cloud
🚕 Pinecone	Proprietary — cloud only	Prototype → billions, if the wallet agrees	True zero ops + serverless	A closed box, and the meter (read units)	None — the dealer's problem	Pinecone only
🚄 Milvus	Apache 2.0 — Lite / Standalone / Distributed	Hundreds of millions → billions	Capacity scales with object storage; GPU_CAGRA; DiskANN	The rails: etcd, Pulsar/Kafka, MinIO/S3	Real ops muscle	Zilliz Cloud

Two synthesis notes the table doesn't fit:

Hybrid search out of the box: yes — Qdrant (dense + sparse, RRF/DBSF fusion), Weaviate (BM25F built in), Milvus (built-in BM25). No — pgvector, Chroma. Pinecone: you bring the sparse vectors yourself (the Qdrant model, not the built-in-BM25 model of Weaviate/Milvus) — check the docs for the current state before betting on it.
Multi-tenancy, natively: Weaviate (tenant = shard), Pinecone (namespaces), Milvus (partition keys / separate databases). pgvector covers it with RLS; Qdrant expects payload filters; Chroma assembles nothing for you.

The recurring math of the series: 1M × 1536-dim × 4 bytes ≈ 6 GB of raw vectors — and an HNSW graph stores a copy of every vector, so roughly double it before picking instance sizes.

Honorable mentions, three lines: Elasticsearch/OpenSearch — if it's already your stack and the vector requirements are modest. Redis — when you need sub-millisecond and already run it. FAISS — an engine, not a car: blazingly fast, but no garage, no service, no keys — you build the car around it.

flowchart TD
    START["You need vector search"] --> Q1{"Prototyping, learning,\nor a personal tool?"}
    Q1 -- "Yes" --> CHROMA["🛴 Chroma"]
    Q1 -- "No" --> Q2{"Data already in Postgres\nand under ~10M vectors?"}
    Q2 -- "Yes" --> PGVECTOR["🚙 pgvector"]
    Q2 -- "No" --> Q3{"Anyone on the team\nwants to own infrastructure?"}
    Q3 -- "Yes — wants to own infra" --> Q4
    Q3 -- "Must self-host (compliance)" --> Q4
    Q4{"Hundreds of millions\nto billions of vectors?"}
    Q4 -- "Yes" --> MILVUS["🚄 Milvus — or rent Zilliz Cloud"]
    Q4 -- "No" --> Q5{"Many tenants, want\nvectorization + hybrid\nfrom the factory?"}
    Q5 -- "Yes" --> WEAVIATE["🚐 Weaviate"]
    Q5 -- "No" --> QDRANT["🏎️ Qdrant"]

Two honest notes on the tree:

No Postgres yet? The wagon is still an option — managed Postgres is one click away (Part 1). The garage is not a prerequisite.
Data can't leave your perimeter AND nobody wants ops? That's a hiring problem, not a database problem. No car in this showroom fixes it — and pretending otherwise is how two-week adventures begin.

The one-day test drive

Pick 2–3 finalists from the tree — not all six. Then:

Before you start

One embedding model for all candidates — the honest-comparison rule since Part 3
Real data: 10–50k real documents and 50–100 real queries from your product. Lorem ipsum measures lorem ipsum
Deploy the gauge you'll actually ride: if production is a cluster, benchmark the cluster shape — the Milvus lesson

(2–3 hours)

Create the schema and payload/metadata indexes before loading — the Qdrant and Milvus lessons
Load the data. Then wait: settled segments, built indexes (benchmark traps #1 and #2). A benchmark on fresh data measures brute force, not your index

(2 hours) — the scorecard

Recall@10 vs exact ground truth. Brute-force the same vectors yourself — at 50k rows it takes seconds:

import numpy as np

# vectors: (N, 1536) of your uploaded embeddings, query: (1536,)
# ground truth must use the SAME metric you query with —
# for cosine, normalize first
scores = vectors @ query
truth_indices = set(np.argsort(scores)[-10:][::-1])   # exact top-10 INDICES into `vectors`

# Option 1: if your DB returns positions in the same order you uploaded,
# compare indices directly
recall = len(truth_indices & set(returned_indices)) / 10

# Option 2: if your DB returns IDs, map indices to IDs first —
# the upload order defines the mapping, keep it consistent
# ids = ["doc_0", "doc_1", ...]          # index i -> id, fixed at upload time
# truth_ids = {ids[i] for i in truth_indices}
# recall = len(truth_ids & set(returned_ids)) / 10

p95 latency at your realistic QPS, not the demo QPS
RAM after indexing — expect roughly 2× the raw vectors (the series rule)
Filtered search: does "similar AND year=2024" return the full LIMIT? (the Part 1 trap)
Insert → immediately search: flaky? Now you know before production does (the taxi and the train)
Kill the process mid-write (self-hosted) or test retry after errors (managed) — then check nothing was lost
Export everything back out — measure the exit in hours, not promises

(1 hour) — the bill

Managed (Pinecone): your real QPS × top_k → read units → dollars. Managed (Qdrant / Weaviate / Zilliz Cloud): RAM + CPU → monthly subscription. Either way, the meter never sleeps
Self-hosted: the RAM you measured → the smallest instance that fits → × 12 months
Fill the scorecard, then sleep on it:

Candidate	recall@10	p95, ms	RAM after index, GB	$/month at your QPS	Exit, hours	Gut feeling
...

Yes, "gut feeling" is a column. DX is a cost of ownership too — you'll pay it every working day.

Next morning: re-run the same queries cold. Numbers that only look good warm are a finding, not a footnote.

The method doesn't expire

Everything in this series was true at the time of writing; databases evolve — verify versions against the docs. The method doesn't expire: judge by cost of ownership, verify on your data, buy for the scale you have, re-check at the scale you reach.

Vector database showroom. Part 6 Milvus — The High-Speed Freight Train

Silver_dev — Fri, 09 Oct 2026 18:58:22 +0000

🚄 Milvus — The High-Speed Freight Train

Billions of vectors aboard, uncontested on the mainline. But nobody rides before the rails are built.

Under the hood: a Go + C++ core, Apache 2.0, a graduated project of the Linux Foundation's LF AI & Data, driven by Zilliz (who also sell the managed ride, Zilliz Cloud). The distributed deployment is a real architecture: proxy, coordinator services, and worker nodes (query, data, index) — all hanging off a central log (Pulsar or Kafka), with etcd for metadata and MinIO/S3 for object storage. Your vectors live in object storage; storage and compute are separated. One train, three gauges: Milvus Lite (embedded, pip install, desk scale), Milvus Standalone (a rail bus — three containers: Milvus itself, etcd for metadata, MinIO for object storage), and Milvus Distributed (the mainline — Helm on Kubernetes).

Where it shines:

Billions of vectors is the home stadium: capacity scales with your object storage, not your RAM budget; horizontal scale means adding worker nodes. This is the tool that made "vector database" a category
GPU acceleration (since v2.4): GPU_CAGRA built on NVIDIA's RAPIDS — for when search is the bottleneck and you have the silicon
DiskANN (since v2.4): the index lives on SSD — vectors beyond RAM, latency traded for capacity
Sparse vectors since v2.4, and since v2.5 a built-in BM25 full-text search — the factory-grade hybrid, no separate sparse embedder required
Multi-tenancy with documented patterns (partition keys, separate databases), RBAC, TLS — and Attu, a proper admin GUI. The only vehicle in the showroom that ships with a cockpit display
One of the largest OSS communities in the category; SDKs for Python/Java/Go/Node; LangChain/LlamaIndex integrations; Zilliz Cloud if you'd rather rent the railway

Where it stalls:

The rails: Distributed means etcd + Pulsar/Kafka + MinIO/S3 + the Milvus pods themselves. Helm charts help, but the ops muscle is non-negotiable. (Lite and Standalone genuinely shrink this — see the manual below)
Bring your own embeddings — a database, not an embedder (same rule as the hatchback and the crossover)
No ACID transactions "like in Postgres": batches are not transactions — the station wagon still owns that lane
Tuning is part of the contract: M, efConstruction, nprobe/ef per index type — and a consistency level per query
Backups run through the dedicated milvus-backup tool: plan it and rehearse it. There's no "it's just my Postgres cluster" simplicity here

What breaks if you skip the manual:

Bought the mainline for the street corner. A composite story from community chats, details changed: a team runs semantic search over 300k documents on distributed Milvus — a small zoo of pods, of which exactly two kinds accept queries — because a big-tech talk mentioned billions. A junior asks: "Why not Postgres? We already have Postgres." Calculator: 300,000 × 1536 dims × 4 bytes ≈ 1.8 GB. The right gauge existed all along: Milvus Lite for the prototype, Standalone for small production, Distributed for the billions. Milvus isn't the mistake — the scale mismatch is
Benchmark trap #2 (the hatchback's cousin): fresh inserts land in growing segments that are searched by brute force until they're sealed and indexed. A naive benchmark right after loading — or on a tiny collection — measures exact search, not your index. Honest numbers: production-like volume, settled segments, warm queries
Consistency levels are per-query (default: bounded): strong / bounded / session / eventually. With weaker levels, "insert → immediately search" tests flake exactly like the taxi's eventual consistency. Pick session or strong for the paths that need it
Metric and dimension are locked at collection creation — same rule as the hatchback and the taxi. The escape hatch here is actually elegant: build the new collection and flip a collection alias — the zero-downtime re-index is a documented pattern
The partition key (if you use partition-key tenancy) is fixed at creation too — retrofitting tenancy later means re-shipping the data

Cost of ownership: the train is free (Apache 2.0); the railroad isn't — count the ops salary, not just the license. Zilliz Cloud (managed, serverless tier included) rents you the whole railway. Self-hosted Lite and Standalone genuinely fit a laptop and a small server respectively.

Mechanics & parts: Zilliz drives development; LF AI & Data provides neutral governance; the community is one of the largest in the category. "Milvus engineers" are rarer than Postgres ones — but this is a Kubernetes-native system your DevOps team can actually operate, with vendor support available when the stakes are high.

✅ Take it if: you're at hundreds of millions to billions of vectors, need GPU or beyond-RAM capacity, run many tenants, have (or hire) real ops muscle — or use Zilliz Cloud and skip the rails

❌ Pass if: you're under ~10M vectors on a single box (the hatchback or the wagon covers it), "we plan to grow" is your only argument, or nobody on the team wants to own a Helm chart

Test drive:

# Milvus Lite runs embedded — no containers needed (Linux/macOS)
# Production gauges: Standalone (3-container compose) or Distributed (Helm on K8s)
from pymilvus import MilvusClient, DataType

client = MilvusClient("./milvus_demo.db")  # the desk model of the train

# explicit schema: scalar fields never appear by themselves (Milvus is schema-first,
# no AutoSchema like Weaviate). auto_id=False keeps our own ids — same as Parts 3–5
schema = client.create_schema(auto_id=False, enable_dynamic_field=False)
schema.add_field("id", DataType.INT64, is_primary=True)
schema.add_field("vector", DataType.FLOAT_VECTOR, dim=1536)
schema.add_field("content", DataType.VARCHAR, max_length=512)
schema.add_field("year", DataType.INT64)

index_params = client.prepare_index_params()
index_params.add_index(field_name="vector", index_type="AUTOINDEX", metric_type="COSINE")

client.create_collection(
    collection_name="docs",
    schema=schema,
    index_params=index_params,
)

client.insert(
    collection_name="docs",
    data=[
        {"id": 1, "vector": embed("Quarterly report 2024"), "content": "Quarterly report 2024", "year": 2024},
        {"id": 2, "vector": embed("Legal contract draft"), "content": "Legal contract draft", "year": 2024},
    ],
)
# note: fresh data sits in "growing segments" searched by brute force until they are
# sealed and indexed (benchmark trap #2). flush() seals segments — but in production
# let auto-sealing do its job; frequent manual flushes are an anti-pattern

# embed() — your embedding function (the same one from Parts 3–5 — honest comparison)
res = client.search(
    collection_name="docs",
    data=[embed("annual financial summary")],
    filter="year == 2024",
    limit=10,
    output_fields=["content", "year"],
)

for hits in res:
    for hit in hits:
        print(hit["id"], round(hit["distance"], 3), hit["entity"].get("year"))

The train is magnificent — on the mainline, where it was built to run. Ask it at 300k vectors — Postgres wins. Ask it at 3 billion — the train wins. Buy for the scale you have; re-check at the scale you reach.

🚦 Final part of the showroom: all six vehicles side by side — the cost-of-ownership table, the decision tree, and a one-day test-drive checklist for the car you pick.

Vector database showroom. Part 5 Pinecone — The Car by Subscription

Silver_dev — Fri, 09 Oct 2026 17:36:20 +0000

🚕 Pinecone — The Car by Subscription

— I want a vector database. I don't want: HNSW tuning, container patching, changelog reading, or ever thinking about RAM.
— Have I got a car for you. You won't have to drive.
— What's the catch?
— No catch. It's a subscription: the meter ticks on every ride, and you can never buy the car. Now — the fine print.

For those who'd rather not drive at all. The fine print: the meter runs on every mile.

Under the hood: the only fully managed player in this showroom. Closed source, no self-hosting — not a limitation, a product decision. New users get the serverless architecture: storage and compute are decoupled and scale on their own. There's nothing to tune — and that's the advertised feature.

Where it shines:

Genuinely zero ops: no upgrades, no manual backups, no memory planning. pip install pinecone → API key → index → production. Of all the cars here, this one starts faster than the scooter
Integrated embedding (optional): ship raw text and Pinecone embeds it via hosted models — a feature the scooter from Part 2 envies. Heads-up: an integrated index is a separate index type and doesn't accept your own vectors — one approach per index. The test drive below uses the classic "bring your own vectors" — backend devs prefer it for apples-to-apples comparison (our promise since Part 3)
Multi-tenancy via namespaces: tenants isolated inside a single index
Best-in-class DX: docs, console, SDKs (Python/JS/Go/Java), LangChain/LlamaIndex integrations — Pinecone is the default of half the RAG tutorials on the internet
Enterprise compliance badges: cloud and region of your choice (AWS/GCP/Azure). Though your data still lives in their cloud — see fine print

Where it stalls:

A closed black box, no workarounds: reading the code, patching it, or moving to your own servers — not possible. If your compliance regime says "data never leaves our perimeter" — walk away, and check this before designing the system
Zero knobs: no hnsw_ef, no quantization — the server decides everything. Unhappy with recall? Your freedom is top_k. That's it
No joins, no SQL — expected; the station wagon is still around
Costs grow non-linearly: high-QPS at large top_k is the plot of those "our Pinecone invoice" posts

What breaks if you skip the manual:

The meter counts what you read: every query burns read units. top_k=100, include_values=true (returning the raw vectors!), and a nightly test run in CI — three shock absorbers burning your budget. Only set include_metadata when you actually need the metadata
Eventual consistency: right after an upsert, a query may not see the fresh vectors. The test "write → immediately read" fails flakily. A pause or retry is the standard pattern
Queries live inside a namespace: you uploaded to "2024" but queried without a namespace — empty result. Not a bug: the default namespace is literally the empty string "" — a separate apartment from "2024"
Metadata types are strict: "2024" (string) and 2024 (number) are different values — a numeric filter won't match strings. Pick the type once, for the whole team
The metric (cosine/dotproduct/euclidean) and dimension are locked at index creation — same rule as the hatchback, except there's no "rebuild the collection on our own servers" escape hatch: new index + re-upload

Cost of ownership: a subscription. Free tier for prototypes; then storage + read/write units. This is the only car in the showroom you cannot buy: there is no self-hosted edition and never will be. You can export your data (fetch, bulk export) — but that's moving your stuff out of a rented apartment, not selling the car.

Mechanics & parts: Pinecone (New York) behind it; the founder came out of Amazon's AI lab. You can't hire a "Pinecone mechanic" — you can't look under the hood. The upside: nothing for you to fix — if it breaks, the dealer repairs it. There's no grease-monkey community by design: all the wrenches belong to the vendor.

✅ Take it if: you have no ops team (and won't), prototype-to-production in one day, spiky traffic, no "data stays in our perimeter" requirement, and a variable bill doesn't scare you

❌ Pass if: your data can't leave your perimeter; you want to steer recall and cost with your own hands; or you're pushing billions of vectors at sustained high QPS — do the TCO math against the train

Test drive:

# modern SDK — pip install -U pinecone
# (the legacy `pinecone-client` package name is deprecated)
from pinecone import Pinecone, ServerlessSpec

pc = Pinecone(api_key="YOUR_API_KEY")

# metric and dimension are locked at creation — same rule as the hatchback
if "docs" not in pc.list_indexes().names():
    pc.create_index(
        name="docs",
        dimension=1536,
        metric="cosine",
        spec=ServerlessSpec(cloud="aws", region="us-east-1"),  # required in the modern SDK
    )

index = pc.Index("docs")

# embed() — your embedding function (the same one from Parts 3–4 — honest comparison)
index.upsert(
    vectors=[
        {"id": "1", "values": embed("Quarterly report 2024"), "metadata": {"year": 2024}},
        {"id": "2", "values": embed("Legal contract draft"), "metadata": {"year": 2024}},
    ],
    namespace="2024",
)
# heads-up: right after upsert, a query may not see these vectors yet (eventual consistency)

# the meter ticks here: top_k and include_metadata cost read units
# include_values=True is the budget-killer from "what breaks" above — only if you truly need raw vectors
res = index.query(
    namespace="2024",
    vector=embed("annual financial summary"),
    filter={"year": {"$eq": 2024}},
    top_k=10,
    include_metadata=True,
)

for match in res["matches"]:
    print(match["id"], round(match["score"], 3), match["metadata"].get("year"))

The whole ride without a single thought about servers. The subscription keeps its promise. The only question: how far will you drive — and what the meter reads at the end of the month.

Vector database showroom. Part 4 Weaviate — The Crossover That Ships Fully Loaded

Silver_dev — Fri, 09 Oct 2026 15:54:32 +0000

🚐 Weaviate — The Crossover That Ships Fully Loaded

Every option already installed: vectorization, hybrid search, multi-tenancy. One question — who services all those options?

Under the hood: a Go core under BSD-3-Clause, one container to start. Three protocols: REST, GraphQL, and gRPC, with the v4 client using gRPC as its fast lane. The philosophy: "bring your data, the factory does the rest" — vectorizer modules, hybrid search, and generation are toggled by config, not external code.

Where it shines:

Factory vectorization: attach a module (local transformers, OpenAI, Cohere, multimodal CLIP) and the database embeds on insert. Contrast with the scooter: there the embedder is hardwired; here it's a factory option you choose
Hybrid, factory-grade: BM25F (the lexical index is already inside) + vectors in a single query, with the alpha knob balancing semantics vs keywords. No separate sparse embedder needed — unlike the hatchback
Native multi-tenancy — the signature feature: tenant = its own shard, isolated search and performance, active/inactive tenants with cold storage. For a SaaS, this is what other databases make you assemble from payload filters
Generative search: RAG inside the database — a generative module builds the answer right next to the retrieved objects
Cross-references between objects: a mini-graph inside your vector DB (Neo4j ambitions excluded)
Above-average operations: built-in backups to S3/GCS/Azure/disk, Prometheus metrics, OIDC auth. The hatchback with its manual snapshots is jealous

Where it stalls:

Factory options need a service bay: self-hosted vectorization modules are separate containers — each eats RAM and needs babysitting. API modules put an external-provider dependency inside your database
No transactions "like in Postgres": batches are not ACID operations
Schema changes: some apply on the fly, but switching the vectorizer or a property type = re-import. Design the schema before loading
Distributed mode exists, but the tuning is plentiful: ef, efConstruction, quantization (scalar/product/binary) trading recall

What breaks if you skip the manual:

AutoSchema: by default the schema is inferred from the first objects — "the factory assembles the trim based on your first order." Wrong types in the first batch and you live with them or re-import. In production, define the schema explicitly
Changing the vectorizer module — or a model deprecation — means a full re-embedding. That's an operation, not a flag
Multi-tenancy is enabled at collection creation. Once on, queries must pass a tenant: an inactive one returns an activation error — not a search across everything. A feature, but a first-time surprise
Python clients v3 and v4 are incompatible: half the tutorials online use v3 syntax that won't run on v4 (even the terms changed: classes → collections). Install v4 (pip install -U weaviate-client) and keep the migration guide handy
Hybrid alpha: 0 = pure vector, 1 = pure BM25 (keyword). Don't copy the default from tutorials — run evals on your own queries

Cost of ownership: free under BSD-3-Clause. Weaviate Cloud (serverless/enterprise) — managed, if you'd rather outsource the service bay. Embedded mode for local tests and CI.

Mechanics & parts: Weaviate B.V. (Amsterdam) behind it; excellent docs, an active community. "Weaviate engineers" are as rare on the market as "Qdrant engineers" — but a backend developer can drive this one.

✅ Take it if: a SaaS with many tenants, you want a BM25+vector hybrid without rolling your own sparse embedder, or you want vectorization and generation bundled in one database

❌ Pass if: your logic lives in SQL (the station wagon), you're counting billions with GPUs (the train), or your ops budget is minimal — a fully-loaded crossover needs a service bay

Test drive:

# weaviate-client v4: pip install -U weaviate-client
# embedded mode downloads binaries once; in production — Docker or Weaviate Cloud
import weaviate
from weaviate.classes.config import Configure, Property, DataType
from weaviate.classes.query import Filter

client = weaviate.connect_to_embedded()

docs = client.collections.create(
    "Document",
    vectorizer_config=Configure.Vectorizer.none(),  # we bring vectors ourselves (hatchback-style)
    properties=[
        Property(name="title", data_type=DataType.TEXT),
        Property(name="year", data_type=DataType.INT),
    ],
)

docs.data.insert(
    properties={"title": "Quarterly report 2024", "year": 2024},
    vector=embed("Quarterly report 2024"),  # embed() — your embedding function
)

# hybrid: BM25F + vectors in one query
# alpha = balance: 0 — vector, 1 — BM25; tune on evals
res = docs.query.hybrid(
    query="annual financial summary",
    vector=embed("annual financial summary"),
    alpha=0.5,
    filters=Filter.by_property("year").equal(2024),
    limit=10,
)

for obj in res.objects:
    print(obj.uuid, obj.metadata.score, obj.properties["title"])

A crossover wins neither with the hatchback's speed nor the scooter's simplicity — it wins on equipment: a whole RAG factory inside one database. You don't pay for the steering wheel; you pay for the service bay that keeps the options running.

Vector database showroom. Part 3 Qdrant — The Hot Hatchback That Carries More Than It Looks

Silver_dev — Thu, 08 Oct 2026 20:32:21 +0000

🏎️ Qdrant — The Hot Hatchback That Carries More Than It Looks

Sharp acceleration, precise handling — and a trunk noticeably bigger than it looks from the outside.

Under the hood: a Rust core shipped as a single binary or container (the Python client even has an embedded/local mode for experiments). Apache 2.0. The signature feature — filterable HNSW: the graph is built with payload indexes in mind, so filters participate in graph traversal instead of being glued on top.

Where it shines:

Remember pgvector's three filter tools? Here filtering is part of the index itself: "similar, but only year=2024" is this car's home turf
Hybrid out of the box: sparse vectors since v1.7, the Query API with prefetch and fusion (RRF/DBSF) since v1.10 — dense + sparse in a single request
Quantization is our "lightweight alloys": int8 shrinks vectors 4×, binary 32×. Originals can live on disk while only compressed copies stay in RAM. Hundreds of millions of vectors on a single node is a real setup, not marketing
Multivectors (ColBERT-style):* several vectors per point, late interaction — something very few databases in this showroom offer Operations: Prometheus metrics, snapshots, API keys + JWT RBAC

Where it stalls:

Bring your own embeddings — it's a database, not an embedder (contrast with last issue's scooter). Clients for Python/JS/Go/Rust, LangChain/LlamaIndex integrations included
Distributed mode (sharding, replication, Raft) is real ops work — simpler than the freight train arriving later in this series, heavier than Postgres
Backups are manual snapshots. No WAL, no point-in-time recovery like the one you're used to in Postgres
Tuning is part of the contract: m, ef_construct, hnsw_ef, quantization with rescoring. Defaults are decent, but a hot hatch likes to be tuned

What breaks if you skip the manual:

The distance function (COSINE/DOT/EUCLID/MANHATTAN) is locked at collection creation. Wrong pick = full reindex — there is no "alter on the fly"
Payload indexes: forget to create them and filtered search degrades to scans. The right order: collection → payload indexes → bulk upload. Adding an index afterwards rebuilds the HNSW graph in the background to wire up the filterable edges
Benchmark trap #1: while a segment stays below the optimizer's indexing_threshold, no HNSW index is built for it — search falls back to brute force, fast and with perfect recall. A naive benchmark on a small collection measures exact search, not HNSW. Honest numbers require production-like volume — or explicitly lowering indexing_threshold
Quantization without rescoring eats recall — and binary quantization is model-sensitive: brilliant on some embeddings, poor on others. Ground truth for comparison: search with exact=true. Showroom thesis: vendor benchmarks are ads — verify on your own data
Named vectors: if the collection was created with named vectors, queries must pass the vector name via the using parameter — otherwise a 400

Cost of ownership: free under Apache 2.0; Qdrant Cloud (managed & hybrid) exists. RAM appetite is flexible — quantization + on-disk originals instead of "6 GB per million."

Mechanics & parts: Qdrant GmbH (Berlin) behind it; the docs are among the best in the industry. "Qdrant engineers" are rare on the market, but this is a database a backend developer can drive — not a twenty-pod zoo.

✅ Take it if: millions to hundreds of millions of vectors, filter-heavy RAG, self-hosting, and you want speed without building railroads

❌ Pass if: your logic lives in SQL and you need joins (the station wagon does those better), or you're counting billions with GPUs — the train arrives later in this series

Test drive:

from qdrant_client import QdrantClient, models

# qdrant-client >= 1.10; for local experiments: QdrantClient(path="./qdrant_data")
client = QdrantClient(url="http://localhost:6333")

client.create_collection(
    collection_name="docs",
    vectors_config=models.VectorParams(size=1536, distance=models.Distance.COSINE),
)

# payload index BEFORE upload — this is how filterable HNSW gets built
client.create_payload_index(
    collection_name="docs",
    field_name="year",
    field_schema=models.PayloadSchemaType.INTEGER,
)

# embed() — your embedding function (OpenAI, BGE, anything)
client.upsert(
    collection_name="docs",
    points=[
        models.PointStruct(id=1, vector=embed("Quarterly report 2024"), payload={"year": 2024}),
        models.PointStruct(id=2, vector=embed("Legal contract draft"), payload={"year": 2024}),
    ],
)

# the filter participates in graph traversal, not glued on top
# query_points returns a QueryResponse — the hits live in .points
res = client.query_points(
    collection_name="docs",
    query=embed("annual financial summary"),
    query_filter=models.Filter(
        must=[models.FieldCondition(key="year", match=models.MatchValue(value=2024))]
    ),
    limit=10,
).points

for point in res:
    print(point.id, point.score, point.payload)

A hatchback doesn't pretend to be a station wagon and doesn't build railroads — it just carries fast. And when your data outgrows the trunk, the API doesn't change: you move to a cluster via snapshots, and the application never notices.

Vector database showroom. Part 2: Chroma — The E-Scooter That Starts in 90 Second

Silver_dev — Sat, 03 Oct 2026 10:30:05 +0000

🛴 Chroma — The E-Scooter That Starts in 90 Seconds

pip install chromadb — and you're already riding. No server, no ports, no API keys.

Under the hood: an open-source embedding database (Apache 2.0, Python-first, Rust core since v0.4). Embedded mode is the default: use PersistentClient to write your data to SQLite + Parquet right on disk (while the basic Client() is ephemeral and loses data on restart — a classic first-day surprise). Need to share it with the team? One command turns the scooter into an HTTP server or a container.

Where it shines:

Three lines to your first search, embeddings included: a local ONNX model runs by default — no OpenAI key, no ongoing network calls (the model downloads once, ~80 MB, on first run), no bills
The default of every RAG tutorial: first-class LangChain and LlamaIndex integrations
Metadata filters (where) and document-content filters (where_document)
Cosine instead of the default L2 — a single parameter
Your data is actually yours: collection.get() dumps everything. Lock-in is measured in hours, not months

Where it stalls:

Single node by design — there is no distributed mode. Single-digit millions of vectors: comfortable. Tens of millions: an expedition with duct tape
The HNSW index lives in RAM: 1M × 1536-dim vectors ≈ 6 GB of raw data — plus roughly the same again for the graph itself (same math as pgvector)
Prototype-grade durability: SQLite + Parquet segments on disk. A hard kill of the process can cost you the latest writes
No BM25 hybrid, no quantization, no RBAC — invisible in a prototype, painfully visible in production

What breaks if you skip the manual:

The scooter that drove itself to production. The classic arc: the prototype grows, "it's basically done, let's ship it" — and at 5M vectors you're looking for a cluster that doesn't exist. Migrating to a "real" database is a day's work; replanning the architecture mid-incident is the day you don't have
No alarm system: token auth at best, TLS is DIY through a reverse proxy. "It's only reachable from the office network" — famous last words
The storage format has changed between major versions before: read the changelog before upgrading

Cost of ownership: free under Apache 2.0. Chroma Cloud exists, but the scooter's honest habitat is "zero infrastructure at all."

Mechanics & parts: job postings for a "Chroma engineer" don't exist — because they're not needed. Any Python developer can fix a scooter with a screwdriver. The community is one of the largest among vector databases.

✅ Take it if: you're prototyping RAG, learning embeddings, running evals in CI, or building a personal tool that will never see the internet

❌ Pass if: this database is about to hold production with paying users — rent a car, not a scooter

Test drive — 90 seconds:

import chromadb
from chromadb.utils import embedding_functions

client = chromadb.PersistentClient(path="./chroma_data")

# explicit local model — reliable and warning-free
default_ef = embedding_functions.DefaultEmbeddingFunction()

collection = client.get_or_create_collection(
    name="docs",
    embedding_function=default_ef,
    metadata={"hnsw:space": "cosine"}
)

collection.add(
    ids=["1", "2"],
    documents=["Quarterly report 2024", "Legal contract draft"],
    metadatas=[{"year": 2024}, {"year": 2024}],
)

# embeddings are local and automatic — the model
# downloads once (~80 MB) on first run
res = collection.query(
    query_texts=["annual financial summary"],
    n_results=2,
    where={"year": 2024},
)

That's the whole vehicle. If it feels too easy — that's the point. Just remember: a scooter's job is to one day step aside for a real car.

Vector database showroom. Part 1 pgvector — The Station Wagon Already in Your Garage.

Silver_dev — Fri, 02 Oct 2026 21:11:46 +0000

Welcome to the Vector Database Showroom — a guided tour through today's most popular vector databases, where we look past the marketing brochures and judge each one by its real cost of ownership. Up first: pgvector, the quiet contender that's probably already sitting in your garage.

🚙 pgvector — The Station Wagon Already in Your Garage

pgvector isn't a separate database. It's a Postgres extension: one CREATE EXTENSION later, your vectors live next to your regular data.

Under the hood: the vector type, two index types (HNSW, IVFFlat), three core distance metrics (L2, cosine, inner product). Since v0.6: halfvec (half the memory) and sparse vectors. Since v0.7: iterative index scans for filtered search.

Where it shines:

ACID transactions: the embedding and its metadata commit atomically. No dual-write sync, no "eventually consistent" surprises
Joins: "find similar documents AND fetch related rows" without an application-level roundtrip
Backups, monitoring, access control, read replicas — everything you've already set up for Postgres covers your vectors for free
Row Level Security for multi-tenant setups

Where it stalls:

Vertical ceiling. Comfortable up to ~1M vectors; workable to ~10M with tuning (halfvec, partitioning, Timescale's pgvectorscale). Beyond that — different league
RAM appetite: 1M × 1536-dim vectors ≈ 6 GB of raw data — plus roughly the same again for the HNSW index itself, which stores a copy of every vector inside the graph. Budget ~12–16 GB of RAM/cache, not 6
Rebuilding the index at scale takes hours, not minutes

What breaks if you skip the manual:

Filters + ANN — you have three tools, pick per scenario. A bare WHERE is applied after the HNSW scan returns its top-k, so you can get fewer rows than LIMIT asked for:
- Pre-filter via b-tree — the classic RAG pattern. Index the filter column (CREATE INDEX ON documents ((meta->>'year'))); on a selective filter, Postgres fetches matching rows first and computes exact distances on just those. 100% recall — and the planner usually picks this route on its own
- Iterative scans (v0.7+) — SET hnsw.iterative_scan = strict_order keeps walking the HNSW graph until the filter is satisfied. The choice when the filter matches many rows and b-tree pre-filtering would scan half the table
- Overfetch — grab LIMIT × 5–10 and filter in the app. Quick, dirty, fine for prototypes
The dimension limits. A vector column stores up to 16,000 dims, but indexes top out at 2,000 (vector) and 4,000 (halfvec). A 3072-dim model like OpenAI's text-embedding-3-large? Won't index as vector — but fits as halfvec (fp16, minimal quality loss). Beyond 4,000 dims: truncate with a Matryoshka-trained model (near-lossless) or move to a dedicated vector DB — Qdrant and Milvus index far higher
Recall disappointing? Raise hnsw.ef_search — the default 40 is conservative
Frequent vector UPDATEs → bloat: every edit rewrites ~6 KB per row. A bulk re-embedding is an operation — plan a VACUUM afterwards

Cost of ownership: free under the PostgreSQL license. Zero extra spend, provided your existing instance has the CPU/RAM headroom. Available on RDS, Aurora, Cloud SQL, AlloyDB, Azure, Supabase, Neon — basically everywhere.

Mechanics & parts: any backend developer can drive this car, and every ORM ships an integration (Django, Rails, SQLAlchemy, Prisma). One honest caveat: the project has historically been driven by one very productive person (Andrew Kane), with a growing contributor base — plus an ecosystem of companies (Supabase, Neon, Timescale) building businesses on top of it. The counterweight: it's a Postgres extension, not a black box — worst case, you're holding a documented SQL type and well-known algorithms.

✅ Take it if: you already run Postgres, you're under ~1M vectors, and data consistency matters (RAG over your own DB)

❌ Pass if: you're heading for billions of vectors or distributed scale — the station wagon won't become a freight train

Test drive:

CREATE EXTENSION vector;

CREATE TABLE documents (
  id bigserial PRIMARY KEY,
  content text,
  meta jsonb,
  embedding vector(1536)
);

CREATE INDEX ON documents
USING hnsw (embedding vector_cosine_ops);

-- b-tree on the filter column → exact pre-filtered search
CREATE INDEX ON documents ((meta->>'year'));

-- operators: <=> cosine | <-> L2 | <#> negative inner product
-- ORDER BY sorts ascending: smallest value = closest neighbor
SELECT id, content FROM documents
WHERE meta->>'year' = '2024'
ORDER BY embedding <=> $1
LIMIT 10;

Gotcha for NumPy/FAISS folks: <#> returns the negative inner product — pgvector makes every operator sort smallest-first.

If you know SQL, you already know pgvector. That's the whole car.

Spring Boot Under the Hood. Part 9: Actuator, DevTools and the Rest of the Toolbox

Silver_dev — Thu, 24 Sep 2026 22:33:54 +0000

This final part gathers the tools that aren't part of the application's core runtime, yet no production project can do without: monitoring, logging, development acceleration, testing, packaging, and native compilation.

9.1. Actuator — Production-Ready Monitoring

Actuator adds ready-made HTTP/JMX endpoints for monitoring and management to your application.

9.1.1. Adding it

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

By default, only /actuator/health and /actuator/info are exposed. The rest are enabled via management.endpoints.web.exposure.include:

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,env,beans

9.1.2. Built-in Endpoints

ID	What it shows
`health`	Application status (UP/DOWN)
`info`	Arbitrary info (`info.*` properties)
`metrics`	Micrometer metrics (JVM, HTTP, DataSource)
`env`	All property sources
`beans`	The full list of beans
`mappings`	All `@RequestMapping` paths
`configprops`	All `@ConfigurationProperties`
`threaddump`	JVM thread dump
`heapdump`	Heap dump (hprof)
`loggers`	View/change logging levels
`shutdown`	Graceful shutdown — removed in Boot 3.4; use `server.shutdown=graceful` instead

9.1.3. Your Own `@Endpoint`

@Component
@Endpoint(id = "featureFlags")
public class FeatureFlagsEndpoint {

    @ReadOperation
    public Map<String, Boolean> getFlags() {
        return Map.of("newCheckout", true, "darkMode", false);
    }

    @WriteOperation
    public void setFlag(@Selector String name, boolean value) {
        // set the flag
    }
}

@ReadOperation → HTTP GET (available at http://localhost:8080/actuator/featureFlags)
@WriteOperation → HTTP POST
@DeleteOperation → HTTP DELETE

9.1.4. HealthIndicators

@Component
public class ExternalServiceHealthIndicator implements HealthIndicator {
    @Override
    public Health health() {
        if (isServiceUp()) {
            return Health.up().withDetail("responseTime", "45ms").build();
        }
        return Health.down().withDetail("error", "Connection refused").build();
    }
}

Actuator collects all HealthIndicator beans and aggregates them into the overall /actuator/health status. The possible statuses are UP, DOWN, OUT_OF_SERVICE, and UNKNOWN. The overall status is the "worst" of them all.

9.1.5. Micrometer

Micrometer is a metrics facade. Actuator automatically registers a MeterRegistry and collects JVM metrics (heap, threads, GC).

@Component
public class OrderMetrics {
    private final Counter orderCounter;
    private final Timer orderTimer;

    public OrderMetrics(MeterRegistry registry) {
        this.orderCounter = Counter.builder("orders.created")
            .description("Number of created orders")
            .register(registry);
        this.orderTimer = Timer.builder("orders.processing.time")
            .register(registry);
    }

    public void onOrderCreated() { orderCounter.increment(); }
    public void recordTime(Runnable task) { orderTimer.record(task); }
}

Prometheus integration:

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

The /actuator/prometheus endpoint serves metrics in the Prometheus format.

9.1.6. Boot 4: Actuator Changes

Packages relocated: org.springframework.boot.actuate.health.Health → org.springframework.boot.health.contributor.Health.
Modularization: Actuator is split into many modules (actuator-web, actuator-jmx, actuator-sbom, etc.).
/actuator/info has been extended: process information is now included.

9.2. Logging

9.2.1. The Defaults

Spring Boot uses SLF4J as the facade and Logback as the implementation. At startup, LoggingApplicationListener (registered in spring.factories) initializes logging before the ApplicationContext is even created.

9.2.2. Configuration

System	File
Logback	`logback-spring.xml` (recommended), `logback.xml`
Log4j2	`log4j2-spring.xml`, `log4j2.xml`
JUL	`logging.properties`

The -spring variants are recommended: they support <springProfile> and <springProperty>.

<!-- logback-spring.xml -->
<configuration>
    <springProfile name="dev">
        <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
            <encoder>
                <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
            </encoder>
        </appender>
    </springProfile>

    <springProfile name="prod">
        <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <file>${LOG_FILE}</file>
            <encoder>
                <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger - %msg%n</pattern>
            </encoder>
        </appender>
    </springProfile>
</configuration>

9.2.3. Levels via Properties

logging:
  level:
    root: INFO
    com.example.myapp: DEBUG
    org.springframework.web: WARN

9.2.4. Structured Logging (Boot 3.4+)

Spring Boot 3.4 added native structured logging support with no extra dependencies:

logging:
  structured:
    format:
      console: ecs   # Elastic Common Schema
      file: logstash

Formats: ecs, logstash, gelf.

9.2.5. Boot 4: Changes

The default encoding is UTF-8 for Logback, matching Log4j2.
No automatic trace/span ID correlation — you need to configure the appender manually.
Logback has been upgraded to a new version; some appenders were removed.

9.3. DevTools — Speeding Up Development

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <optional>true</optional>
</dependency>

9.3.1. Automatic Restart

DevTools uses two ClassLoaders:

ClassLoader	What it loads
Base ClassLoader	Immutable JARs (Spring, third-party libraries)
Restart ClassLoader	Your application's classes (the frequently changing ones)

When a classpath file changes, DevTools re-creates only the Restart ClassLoader while the Base one stays. That's what makes the restart several times faster than a full one.

9.3.2. LiveReload

The built-in LiveReload server automatically refreshes the browser when resources change (HTML, CSS, JS). Requires a LiveReload browser extension. Disabled via spring.devtools.livereload.enabled=false.

9.3.3. include/exclude Configuration

# META-INF/spring-devtools.properties
restart.exclude.companycommonlibs=/mycorp-common-[\\w-]+\.jar
restart.include.projectcommon=/mycorp-myproj-[\\w-]+\.jar

exclude — JARs loaded by the Base ClassLoader. include — the opposite, loaded by the Restart ClassLoader.

9.3.4. Global Settings

A .spring-boot-devtools.properties file in $HOME applies to all projects.

Important: DevTools must never make it into production. optional=true plus Maven/Gradle excludes it from the final JAR.

9.4. Testing

9.4.1. @SpringBootTest — the Full Context

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
class MyApplicationTests {

    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    void contextLoads() {
        ResponseEntity<String> response = restTemplate.getForEntity("/api/hello", String.class);
        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
    }
}

webEnvironment:

MOCK (default) — no real server, MockMvc
RANDOM_PORT — a real server on a random port
DEFINED_PORT — on the configured port
NONE — no web environment

9.4.2. Slice Tests — Narrow Contexts

Annotation	What it loads	What to mock
`@WebMvcTest`	Only MVC: controllers, `@ControllerAdvice`, filters	Services via `@MockitoBean`
`@DataJpaTest`	Only JPA: repositories, `@Entity`, DataSource	Usually H2 in-memory
`@JsonTest`	Only Jackson/Gson	—
`@RestClientTest`	Only the REST client (`RestTemplate`, `WebClient`)	The server via MockWebServer

@WebMvcTest(UserController.class)
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockitoBean
    private UserService userService;

    @Test
    void shouldReturnUser() throws Exception {
        when(userService.findById(1L)).thenReturn(new User(1L, "Alice"));

        mockMvc.perform(get("/api/users/1"))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.name").value("Alice"));
    }
}

The key advantage of slice tests: the context loads faster because only the relevant slice of auto-configuration is enabled.

9.4.3. @MockitoBean — Replacing @MockBean in Boot 4

A critical breaking change in Boot 4:

// Boot 3.x (deprecated in 3.4, removed in 4.0)
@MockBean
private UserService userService;

// Boot 4.x
import org.springframework.test.context.bean.override.mockito.MockitoBean;
@MockitoBean
private UserService userService;

@MockBean and @SpyBean are gone in Boot 4. The replacements are @MockitoBean and @MockitoSpyBean from Spring Framework.

9.4.4. ApplicationContextRunner — Testing Auto-configurations

For testing your own auto-configurations:

class MyAutoConfigurationTests {

    private final ApplicationContextRunner contextRunner = new ApplicationContextRunner()
        .withConfiguration(AutoConfigurations.of(MyServiceAutoConfiguration.class))
        .withPropertyValues("my.service.endpoint=http://localhost:9090");

    @Test
    void shouldCreateMyService() {
        contextRunner.run(context -> {
            assertThat(context).hasSingleBean(MyService.class);
        });
    }

    @Test
    void shouldBackOffWhenCustomBeanPresent() {
        contextRunner
            .withUserConfiguration(CustomConfig.class)
            .run(context -> {
                assertThat(context).hasSingleBean(MyService.class);
                assertThat(context.getBean(MyService.class)).isInstanceOf(CustomMyService.class);
            });
    }
}

ApplicationContextRunner lets you test auto-configuration conditions in isolation, without loading the whole application.

9.5. Build and Packaging

9.5.1. spring-boot-maven-plugin

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

The repackage goal creates an executable JAR (a fat jar):

mvn clean package
java -jar target/myapp-0.0.1-SNAPSHOT.jar

9.5.2. Layered JAR

Since Boot 2.3, the JAR can be split into layers for efficient Docker caching:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <layers>
            <enabled>true</enabled>
        </layers>
    </configuration>
</plugin>

Layers (from rarely changing to frequently changing):

dependencies — stable dependencies
spring-boot-loader — the loader
snapshot-dependencies — snapshots
application — your code

Dockerfile:

FROM eclipse-temurin:21-jre AS builder
WORKDIR /app
COPY target/myapp-*.jar app.jar
RUN java -Djarmode=tools -jar app.jar extract --layers --launcher

FROM eclipse-temurin:21-jre
WORKDIR /app
COPY --from=builder /app/dependencies/ ./
COPY --from=builder /app/spring-boot-loader/ ./
COPY --from=builder /app/snapshot-dependencies/ ./
COPY --from=builder /app/application/ ./
ENTRYPOINT ["java", "org.springframework.boot.loader.launch.JarLauncher"]

9.5.3. JarLauncher

JarLauncher is the fat jar's entry point. It lives in spring-boot-loader and is responsible for:

Reading MANIFEST.MF (Main-Class: org.springframework.boot.loader.launch.JarLauncher)
Building a URLClassLoader with all the nested JARs
Delegating to the Start-Class (your main class)

There's also WarLauncher and PropertiesLauncher (for external configurations).

9.5.4. Buildpacks

mvn spring-boot:build-image

Spring Boot uses Paketo Buildpacks to create an OCI image without a Dockerfile:

<plugin>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-maven-plugin</artifactId>
    <configuration>
        <image>
            <name>myregistry/myapp:${project.version}</name>
        </image>
    </configuration>
</plugin>

9.5.5. Boot 4: Changes

Starters renamed: spring-boot-starter-web → spring-boot-starter-webmvc.
Undertow removed (incompatible with Servlet 6.1).
spring-boot-loader remains, but the packages have been relocated.

9.6. AOT and GraalVM Native Image (an Overview)

9.6.1. What Is AOT

Ahead-of-Time — processing the application at build time rather than at runtime. Spring Boot 3+ performs AOT processing that:

Scans all @Configuration, @Bean, @Component classes.
Generates Java code for bean registration (instead of reflection).
Registers RuntimeHints — hints for GraalVM.

Why: GraalVM Native Image compiles Java into a native executable. Reflection, dynamic proxies, and resource loading only work in a native image if you declare them at build time.

9.6.2. RuntimeHintsRegistrar

public class MyRuntimeHints implements RuntimeHintsRegistrar {
    @Override
    public void registerHints(RuntimeHints hints, ClassLoader classLoader) {
        hints.reflection().registerType(MyDto.class, MemberCategory.values());
        hints.resources().registerPattern("my-config/*.json");
    }
}

Registration:

@ImportRuntimeHints(MyRuntimeHints.class)
@Configuration
public class MyConfig { }

9.6.3. @RegisterReflectionForBinding — a Shortcut

@Configuration
@RegisterReflectionForBinding({User.class, UserDto.class})
public class JacksonConfig { }

The annotation registers reflection hints for DTOs that get serialized by Jackson.

9.6.4. Building a Native Image

mvn -Pnative native:compile

The result is a native executable:

./target/myapp

Advantages:

Instant startup (milliseconds instead of seconds)
Lower memory consumption
Smaller image size

Limitations:

No dynamic class loading
No JIT (lower peak performance)
Longer builds
Not all libraries are supported

9.6.5. Boot 4: AOT by Default

In Boot 4, AOT processing is more aggressive: reflection-free by default for most scenarios. BeanRegistrar (introduced in Spring Framework 7) is the primary way to register beans for AOT, replacing reflection-based @Bean methods.

9.7. Summary Table: Boot 3 vs Boot 4

Aspect	Spring Boot 3.x	Spring Boot 4.x
Actuator packages	`org.springframework.boot.actuate.health`	`org.springframework.boot.health.contributor`
Actuator modules	A single `spring-boot-actuator`	Many modules (web, jmx, sbom...)
Default logging	Logback, charset depends on the OS	Logback, UTF-8 always
Structured logging	Introduced in 3.4	Fully integrated
Test annotations	`@MockBean`, `@SpyBean`	Removed; replaced by `@MockitoBean`, `@MockitoSpyBean`
Starters	`spring-boot-starter-web`	`spring-boot-starter-webmvc`
AOT	Opt-in, `-Pnative`	More aggressive, reflection-free
Buildpacks	Supported	Supported, improved
Layered JAR	Present	Present, improved

9.8. Key Takeaways

Actuator — not just /health. Custom endpoints via @Endpoint + @ReadOperation/@WriteOperation. HealthIndicator — for checking external services. Micrometer — for metrics.
Logging is initialized before the ApplicationContext. Use logback-spring.xml, not logback.xml. Since Boot 3.4 — structured logging out of the box.
DevTools uses two ClassLoaders: Base (stable JARs) and Restart (your code). It restarts only the latter.
Testing: @SpringBootTest — the full context; slice tests — narrow contexts. ApplicationContextRunner — for testing auto-configurations.
@MockBean → @MockitoBean — a critical breaking change in Boot 4.
Layered JAR — splitting into layers for Docker caching. JarLauncher — the fat jar's entry point.
Buildpacks — an OCI image without a Dockerfile: mvn spring-boot:build-image.
AOT — build-time processing for GraalVM. @RegisterReflectionForBinding — for DTOs. Native image: instant startup, but with limitations.

The End of the Series

Spring Boot Under the Hood. Part 8: Graceful Exit — How Spring Boot Starts and Stops

Silver_dev — Thu, 24 Sep 2026 20:46:16 +0000

In Part 1, we left off where SpringApplication.run() calls callRunners() and publishes ApplicationReadyEvent. Now let's look at those steps in detail — plus the complete application shutdown cycle, from the JVM shutdown hook down to @PreDestroy.

8.1. ApplicationRunner and CommandLineRunner — the Entry Point into the "Ready" Application

Once the context is fully up (all beans created, Tomcat running), Spring Boot invokes the beans that implement ApplicationRunner or CommandLineRunner.

@FunctionalInterface
public interface ApplicationRunner {
    void run(ApplicationArguments args) throws Exception;
}

@FunctionalInterface
public interface CommandLineRunner {
    void run(String... args) throws Exception;
}

The key difference is the argument format:

Interface	Parameter	Example access
`CommandLineRunner`	`String[]` (raw)	`args[0]` → `--server.port=9090`
`ApplicationRunner`	`ApplicationArguments`	`args.getOptionNames()` → `[server.port]`

ApplicationArguments is an already-parsed object that Spring Boot builds from the String[]:

DefaultApplicationArguments args = new DefaultApplicationArguments(sourceArgs);
// args.getOptionNames() → Set<String>
// args.getOptionValues("server.port") → List<String>
// args.getSourceArgs() → String[]
// args.getNonOptionArgs() → List<String>

8.2. The Order in Which Runners Are Invoked

Inside SpringApplication.callRunners():

private void callRunners(ApplicationContext context, ApplicationArguments args) {
    List<Object> runners = new ArrayList<>();
    runners.addAll(context.getBeansOfType(ApplicationRunner.class).values());
    runners.addAll(context.getBeansOfType(CommandLineRunner.class).values());
    AnnotationAwareOrderComparator.sort(runners);
    for (Object runner : new LinkedHashSet<>(runners)) {
        if (runner instanceof ApplicationRunner applicationRunner) {
            callRunner(applicationRunner, args);
        }
        if (runner instanceof CommandLineRunner commandLineRunner) {
            callRunner(commandLineRunner, args);
        }
    }
}

Important details:

Both types are collected into a single list.
Sorting is done via AnnotationAwareOrderComparator — by @Order / Ordered.
@Order only affects the order in which run() is invoked — not the order in which the beans are created.
If @Order isn't specified, the order is undefined.

8.3. The Rule: Runners Instead of @PostConstruct

The key Spring Boot rule: tasks that should run at application startup (after the context is fully initialized) should be implemented via ApplicationRunner or CommandLineRunner — not via @PostConstruct.

Why:

@PostConstruct runs during bean initialization, when not all beans are ready yet.
Runners are invoked after the entire context has been refreshed, all beans are created, and the web server is running.
Runners get access to ApplicationArguments.

8.4. Graceful Shutdown

Since Spring Boot 2.3, graceful shutdown is built in.

What happens:

The application receives a SIGTERM signal (e.g., from Kubernetes).
The JVM shutdown hook initiates context.close().
The first phase — stop accepting new requests.
Existing requests get a grace period to finish.
Once all requests are done — the beans are destroyed.

Configuration:

server:
  shutdown: graceful
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s

server.shutdown can be graceful or immediate (the default). timeout-per-shutdown-phase is the maximum time to wait for requests to complete (30 seconds by default).

Behavior by server:

Server	How it rejects new requests
Tomcat	At the network level (stops accepting connections)
Jetty	At the network level
Reactor Netty	At the network level
Undertow	Accepts the connection but responds with `503 Service Unavailable`

Important: graceful shutdown only works when a proper SIGTERM is received. If you stop the application from your IDE (the Stop button), the IDE may send SIGKILL, and graceful shutdown won't kick in.

8.5. WebServerGracefulShutdownLifecycle — the Implementation

As we saw in Part 7, when the WebServer is created, two lifecycle beans are registered:

getBeanFactory().registerSingleton("webServerGracefulShutdown", 
    new WebServerGracefulShutdownLifecycle(this.webServer));
getBeanFactory().registerSingleton("webServerStartStop", 
    new WebServerStartStopLifecycle(this, this.webServer));

WebServerGracefulShutdownLifecycle implements SmartLifecycle

class WebServerGracefulShutdownLifecycle implements SmartLifecycle {
    private final WebServer webServer;
    private volatile boolean running;

    @Override
    public void start() {
        this.running = true;
    }

    @Override
    public void stop(Runnable callback) {
        this.running = false;
        this.webServer.shutDownGracefully((result) -> callback.run());
    }

    @Override
    public int getPhase() {
        return Integer.MAX_VALUE;  // ← the highest phase
    }
}

Key point: getPhase() = Integer.MAX_VALUE. During shutdown, SmartLifecycle beans are stopped in descending phase order, so the web server's graceful shutdown happens first — before the beans that may still be processing requests (DataSource, services, etc.) are destroyed.

8.6. SmartLifecycle and LifecycleProcessor — the Start/Stop Order

SmartLifecycle extends Lifecycle and Phased:

public interface SmartLifecycle extends Lifecycle, Phased {
    boolean isAutoStartup();
    void stop(Runnable callback);

    @Override
    default int getPhase() {
        return 0;
    }
}

The ordering rules:

Phase	Startup	Shutdown
`Integer.MIN_VALUE`	First	Last
`0` (default)	Middle	Middle
`Integer.MAX_VALUE`	Last	First

At startup (onRefresh()): phases are sorted in ascending order — MIN_VALUE starts first, MAX_VALUE last.

At shutdown (onClose()): phases are sorted in descending order — MAX_VALUE stops first, MIN_VALUE last.

This is driven by the DefaultLifecycleProcessor:

public class DefaultLifecycleProcessor implements LifecycleProcessor, BeanFactoryAware {
    private long timeoutPerShutdownPhase = 30000;  // 30 seconds

    @Override
    public void onRefresh() {
        startBeans(true);  // all SmartLifecycle beans with isAutoStartup() == true
    }

    @Override
    public void onClose() {
        stopBeans();       // all running Lifecycle beans
    }
}

timeoutPerShutdownPhase is the maximum wait time for a single phase. If a bean hasn't finished its stop() within that time — Spring moves on without waiting for it.

8.7. The JVM Shutdown Hook — How the JVM Knows It's Time to Stop

SpringApplication.refreshContext() automatically registers a shutdown hook:

private void refreshContext(ConfigurableApplicationContext context) {
    if (this.registerShutdownHook) {
        try {
            context.registerShutdownHook();
        } catch (AccessControlException ex) {
            // Not allowed in some environments
        }
    }
    refresh(context);
}

registerShutdownHook is true by default. It can be disabled via SpringApplication.setRegisterShutdownHook(false).

Inside AbstractApplicationContext:

public void registerShutdownHook() {
    if (this.shutdownHook == null) {
        this.shutdownHook = new Thread(SHUTDOWN_HOOK_THREAD_NAME) {
            @Override
            public void run() {
                synchronized (startupShutdownMonitor) {
                    doClose();
                }
            }
        };
        Runtime.getRuntime().addShutdownHook(this.shutdownHook);
    }
}

The shutdown chain:

SIGTERM from the OS / Ctrl+C / kill <pid>
    │
    ▼
JVM Shutdown Hook (Thread "SpringContextShutdownHook")
    │
    ▼
AbstractApplicationContext.doClose()
    │
    ├─ 1. LifecycleProcessor.onClose()
    │       └─ SmartLifecycle.stop() — descending phase order
    │             ├─ WebServerGracefulShutdownLifecycle (MAX_VALUE) — graceful shutdown
    │             ├─ WebServerStartStopLifecycle (MAX-1) — tomcat.stop()
    │             └─ ... custom SmartLifecycle beans
    │
    ├─ 2. destroyBeans()
    │       └─ for each singleton:
    │             ├─ @PreDestroy (DestructionAwareBeanPostProcessor)
    │             ├─ DisposableBean.destroy()
    │             └─ @Bean(destroyMethod) / AutoCloseable.close()
    │
    ├─ 3. closeBeanFactory()
    │
    └─ 4. active.set(false)

8.8. Closing the Context Manually

If you need to close the context programmatically (e.g., in tests or a CLI application):

ConfigurableApplicationContext context = SpringApplication.run(MyApp.class, args);
// ... work
context.close();  // → doClose()

Or via SpringApplication.exit():

int exitCode = SpringApplication.exit(context, () -> 0);
System.exit(exitCode);

8.9. Spring Boot 3 vs Spring Boot 4 — the Differences

Aspect	Spring Boot 3.x	Spring Boot 4.x
Graceful shutdown	Built in, `server.shutdown=graceful`	Built in, enabled by default for all embedded servers
Undertow	Supported	Removed (incompatible with Servlet 6.1)
Jetty graceful shutdown	`StatisticsHandler`	`GracefulHandler` (changed in 4.2)
`WebServerGracefulShutdownLifecycle`	`org.springframework.boot.web.server`	Modular structure, packages relocated
`ApplicationRunner` / `CommandLineRunner`	Unchanged	Unchanged
`SmartLifecycle` / `LifecycleProcessor`	Unchanged	Unchanged
JVM shutdown hook	`true` by default	`true` by default
Deadlock fix	—	Spring Framework 7.0.4: fixed a deadlock with concurrent shutdown hooks (issue #36260)

The key change in Boot 4: graceful shutdown is enabled by default for all embedded servers. This means that on SIGTERM, the application automatically stops accepting new requests and waits for the existing ones to complete — with zero configuration.

8.10. Key Takeaways

ApplicationRunner vs CommandLineRunner — the only difference is the argument format (ApplicationArguments vs String[]). ApplicationRunner is preferred.
Runner ordering — via @Order / Ordered. Runners are invoked after the context is fully initialized but before ApplicationReadyEvent.
@PostConstruct ≠ runner. "At application startup" tasks belong in runners.
Graceful shutdown — server.shutdown=graceful + spring.lifecycle.timeout-per-shutdown-phase. Enabled by default in Boot 4.
SmartLifecycle ordering: startup in ascending phase, shutdown in descending. WebServerGracefulShutdownLifecycle has phase = MAX_VALUE, so it stops first.
The JVM shutdown hook is registered automatically (registerShutdownHook = true). It's what triggers context.close() on SIGTERM / Ctrl+C.
The shutdown chain: shutdown hook → doClose() → LifecycleProcessor.onClose() → destroyBeans() → @PreDestroy → DisposableBean.destroy().
Boot 4: graceful shutdown by default, Undertow removed, the shutdown-hook deadlock fixed.

Spring Boot Under the Hood. Part 7: From Embedded Tomcat to Your @RestController

Silver_dev — Thu, 24 Sep 2026 19:17:02 +0000

We've reached the point where refresh() calls onRefresh() on the context. For web applications, onRefresh() is where the embedded web server is created and started — we saw this moment on the diagram in Part 6. Let's break down how Spring Boot picks the server, creates the DispatcherServlet, and handles errors.

7.1. Servlet vs Reactive — Two Parallel Worlds

Spring Boot supports two stacks:

Stack	WebApplicationType	Default server	Context
Spring MVC	`SERVLET`	Tomcat	`AnnotationConfigServletWebServerApplicationContext`
Spring WebFlux	`REACTIVE`	Reactor Netty	`AnnotationConfigReactiveWebServerApplicationContext`

The choice happens in the SpringApplication constructor via deduceWebApplicationType(). If DispatcherServlet (Spring MVC) is on the classpath → SERVLET. If DispatcherHandler (WebFlux) is present without MVC → REACTIVE.

Important: if both are on the classpath, SERVLET wins. Spring Boot gives MVC priority as the "older" stack.

7.2. Web Server Auto-configuration — ServletWebServerFactoryAutoConfiguration

The main class for the Servlet stack:

@AutoConfiguration
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)
@ConditionalOnClass(ServletRequest.class)
@ConditionalOnWebApplication(type = Type.SERVLET)
@EnableConfigurationProperties(ServerProperties.class)
@Import({ 
    ServletWebServerFactoryAutoConfiguration.BeanPostProcessorsRegistrar.class,
    ServletWebServerFactoryConfiguration.EmbeddedTomcat.class,
    ServletWebServerFactoryConfiguration.EmbeddedJetty.class,
    ServletWebServerFactoryConfiguration.EmbeddedUndertow.class 
})
public class ServletWebServerFactoryAutoConfiguration {

    @Bean
    public ServletWebServerFactoryCustomizer servletWebServerFactoryCustomizer(
            ServerProperties serverProperties) {
        return new ServletWebServerFactoryCustomizer(serverProperties);
    }
}

Key points:

@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE) — the server is created before most other auto-configurations.
@Import pulls in three nested configurations — for Tomcat, Jetty, and Undertow. Each one is activated via @ConditionalOnClass.

7.2.1. EmbeddedTomcat — Picking the Server

@Configuration(proxyBeanMethods = false)
@ConditionalOnClass({ Servlet.class, Tomcat.class, UpgradeProtocol.class })
@ConditionalOnMissingBean(value = ServletWebServerFactory.class, 
    search = SearchStrategy.CURRENT)
static class EmbeddedTomcat {

    @Bean
    TomcatServletWebServerFactory tomcatServletWebServerFactory(
            ObjectProvider<TomcatConnectorCustomizer> connectorCustomizers,
            ObjectProvider<TomcatContextCustomizer> contextCustomizers,
            ObjectProvider<TomcatProtocolHandlerCustomizer<?>> protocolHandlerCustomizers) {
        // ...
        return factory;
    }
}

The selection logic:

If Tomcat.class is on the classpath and there's no custom ServletWebServerFactory — a TomcatServletWebServerFactory is created.
If you swap Tomcat for spring-boot-starter-jetty — @ConditionalOnClass(Tomcat.class) fails, and EmbeddedJetty kicks in.
If you declare your own ServletWebServerFactory — @ConditionalOnMissingBean backs off, and your factory wins.

7.3. ServletWebServerApplicationContext.onRefresh() — Creating the Server

The entry point is onRefresh() in ServletWebServerApplicationContext:

@Override
protected void onRefresh() {
    super.onRefresh();
    try {
        createWebServer();
    } catch (Throwable ex) {
        throw new ApplicationContextException("Unable to start web server", ex);
    }
}

createWebServer():

private void createWebServer() {
    WebServer webServer = this.webServer;
    ServletContext servletContext = getServletContext();
    if (webServer == null && servletContext == null) {
        StartupStep createWebServer = getApplicationStartup()
            .start("spring.boot.webserver.create");
        ServletWebServerFactory factory = getWebServerFactory();
        this.webServer = factory.getWebServer(getSelfInitializer());
        createWebServer.tag("factory", factory.getClass().toString());
        getBeanFactory().registerSingleton("webServerGracefulShutdown", 
            new WebServerGracefulShutdownLifecycle(this.webServer));
        getBeanFactory().registerSingleton("webServerStartStop", 
            new WebServerStartStopLifecycle(this, this.webServer));
    } else if (servletContext != null) {
        // ... embedded container
    }
}

Key steps:

getWebServerFactory() — fetches the ServletWebServerFactory from the context.
factory.getWebServer(getSelfInitializer()) — creates the WebServer and passes a callback for initializing the ServletContext.
Two lifecycle beans are registered:
- webServerStartStop — starts/stops the server
- webServerGracefulShutdown — graceful shutdown

7.3.1. getSelfInitializer() — the Bridge to ServletContextInitializer

private org.springframework.boot.web.servlet.ServletContextInitializer getSelfInitializer() {
    return this::selfInitialize;
}

private void selfInitialize(ServletContext servletContext) throws ServletException {
    prepareWebApplicationContext(servletContext);
    registerApplicationScope(servletContext);
    WebApplicationContextUtils.registerEnvironmentBeans(getBeanFactory(), servletContext);
    for (ServletContextInitializer beans : getServletContextInitializerBeans()) {
        beans.onStartup(servletContext);
    }
}

ServletContextInitializer is a Spring Boot SPI interface:

@FunctionalInterface
public interface ServletContextInitializer {
    void onStartup(ServletContext servletContext) throws ServletException;
}

Every bean implementing ServletContextInitializer is invoked when the server starts. This is exactly how the DispatcherServlet, filters, and listeners get registered.

7.3.2. ServletContextInitializerBeans — Collecting All the Initializers

public class ServletContextInitializerBeans 
        extends AbstractCollection<ServletContextInitializer> {

    public ServletContextInitializerBeans(ListableBeanFactory beanFactory, 
            Class<? extends ServletContextInitializer>... initializerTypes) {
        // 1. Collects all ServletContextInitializer beans
        // 2. Collects all ServletRegistrationBean, FilterRegistrationBean,
        //    ServletListenerRegistrationBean instances
        // 3. Sorts them via @Order / Ordered
    }
}

What ends up in here:

DispatcherServletRegistrationBean — registers the DispatcherServlet (from DispatcherServletAutoConfiguration)
Custom Filters (Spring Security, etc.)
@WebServlet, @WebFilter, @WebListener (with @ServletComponentScan)

7.4. WebServerStartStopLifecycle — Starting Tomcat

Once the WebServer is created, a lifecycle bean is registered:

class WebServerStartStopLifecycle implements SmartLifecycle {
    private final ServletWebServerApplicationContext applicationContext;
    private final WebServer webServer;
    private volatile boolean running;

    @Override
    public void start() {
        this.webServer.start();
        this.running = true;
        this.applicationContext.publishEvent(
            new ServletWebServerInitializedEvent(this.webServer, this.applicationContext));
    }

    @Override
    public void stop() {
        this.webServer.stop();
        this.running = false;
    }

    @Override
    public int getPhase() {
        return Integer.MAX_VALUE - 1;  // starts almost last
    }
}

SmartLifecycle callbacks fire in finishRefresh() → lifecycleProcessor.onRefresh(). getPhase() = Integer.MAX_VALUE - 1 means the server starts after all the other lifecycle beans.

The order:

refresh() → finishRefresh() → lifecycleProcessor.onRefresh()
WebServerStartStopLifecycle.start() → tomcat.start()
ServletWebServerInitializedEvent is published

7.5. DispatcherServletAutoConfiguration — Creating the DispatcherServlet

@AutoConfiguration(after = ServletWebServerFactoryAutoConfiguration.class)
@ConditionalOnClass(DispatcherServlet.class)
@AutoConfigureAfter(ServletWebServerFactoryAutoConfiguration.class)
public class DispatcherServletAutoConfiguration {

    @Configuration(proxyBeanMethods = false)
    @ConditionalOnClass(DispatcherServlet.class)
    @EnableConfigurationProperties(WebMvcProperties.class)
    protected static class DispatcherServletConfiguration {

        @Bean(name = DispatcherServletAutoConfiguration.DEFAULT_DISPATCHER_SERVLET_BEAN_NAME)
        public DispatcherServlet dispatcherServlet(WebMvcProperties webMvcProperties) {
            DispatcherServlet dispatcherServlet = new DispatcherServlet();
            dispatcherServlet.setDispatchOptionsRequest(
                webMvcProperties.isDispatchOptionsRequest());
            dispatcherServlet.setDispatchTraceRequest(
                webMvcProperties.isDispatchTraceRequest());
            // ...
            return dispatcherServlet;
        }

        @Bean
        public DispatcherServletRegistrationBean dispatcherServletRegistration(
                DispatcherServlet dispatcherServlet, WebMvcProperties webMvcProperties,
                ObjectProvider<MultipartConfigElement> multipartConfig) {
            DispatcherServletRegistrationBean registration = 
                new DispatcherServletRegistrationBean(dispatcherServlet, 
                    webMvcProperties.getServlet().getPath());
            registration.setName(DEFAULT_DISPATCHER_SERVLET_BEAN_NAME);
            registration.setLoadOnStartup(webMvcProperties.getServlet().getLoadOnStartup());
            multipartConfig.ifAvailable(registration::setMultipartConfig);
            return registration;
        }
    }
}

Two key beans:

dispatcherServlet — the DispatcherServlet itself.
dispatcherServletRegistration — a DispatcherServletRegistrationBean, which implements ServletContextInitializer. When the server starts, it registers the DispatcherServlet in the ServletContext.

Ordering: @AutoConfigureAfter(ServletWebServerFactoryAutoConfiguration.class) guarantees that the DispatcherServlet is created after the ServletWebServerFactory has been defined.

7.6. WebMvcAutoConfiguration — Wiring Up Spring MVC

@AutoConfiguration(after = { DispatcherServletAutoConfiguration.class, 
    TaskExecutionAutoConfiguration.class, ValidationAutoConfiguration.class })
@ConditionalOnWebApplication(type = Type.SERVLET)
@ConditionalOnClass({ Servlet.class, DispatcherServlet.class, WebMvcConfigurer.class })
@ConditionalOnMissingBean(WebMvcConfigurationSupport.class)
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE + 10)
@ImportRuntimeHints(WebResourcesRuntimeHints.class)
public class WebMvcAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public InternalResourceViewResolver defaultViewResolver() { ... }

    @Bean
    @ConditionalOnMissingBean
    public RequestMappingHandlerAdapter requestMappingHandlerAdapter(...) { ... }

    @Bean
    @ConditionalOnMissingBean
    public RequestMappingHandlerMapping requestMappingHandlerMapping(...) { ... }

    @Bean
    @ConditionalOnMissingBean
    public HttpMessageConverters messageConverters(...) { ... }
}

@ConditionalOnMissingBean(WebMvcConfigurationSupport.class) — the key point. If you add @EnableWebMvc, Spring Boot backs off, and the entire MVC auto-configuration is disabled. You get vanilla Spring MVC without Boot's customizations.

What WebMvcAutoConfiguration creates:

RequestMappingHandlerMapping — mapping URLs → controller methods
RequestMappingHandlerAdapter — invoking controller methods
HttpMessageConverters — Jackson, String, ByteArray, etc.
InternalResourceViewResolver — for JSPs
MessageSource — i18n
Validator — JSR-380

7.7. ErrorMvcAutoConfiguration — Error Handling

/error is not part of Spring MVC. It's a Spring Boot add-on.

@AutoConfiguration
@ConditionalOnWebApplication(type = Type.SERVLET)
@ConditionalOnClass({ Servlet.class, DispatcherServlet.class })
@AutoConfigureBefore(WebMvcAutoConfiguration.class)
@EnableConfigurationProperties({ ServerProperties.class, WebMvcProperties.class })
public class ErrorMvcAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean(value = ErrorAttributes.class, search = SearchStrategy.CURRENT)
    public DefaultErrorAttributes errorAttributes() {
        return new DefaultErrorAttributes();
    }

    @Bean
    @ConditionalOnMissingBean(value = ErrorController.class, search = SearchStrategy.CURRENT)
    public BasicErrorController basicErrorController(ErrorAttributes errorAttributes,
            ObjectProvider<ErrorViewResolver> errorViewResolvers) {
        return new BasicErrorController(errorAttributes, this.serverProperties.getError(),
            errorViewResolvers.orderedStream().toList());
    }

    @Bean
    public ErrorPageCustomizer errorPageCustomizer(DispatcherServletPath dispatcherServletPath) {
        return new ErrorPageCustomizer(this.serverProperties, dispatcherServletPath);
    }
}

7.7.1. BasicErrorController — the /error Handler

@Controller
@RequestMapping("${server.error.path:${error.path:/error}}")
public class BasicErrorController extends AbstractErrorController {

    @RequestMapping(produces = MediaType.TEXT_HTML_VALUE)
    public ModelAndView errorHtml(HttpServletRequest request, HttpServletResponse response) {
        HttpStatus status = getStatus(request);
        Map<String, Object> model = Collections.unmodifiableMap(
            getErrorAttributes(request, getErrorAttributeOptions(request, MediaType.TEXT_HTML)));
        response.setStatus(status.value());
        ModelAndView modelAndView = resolveErrorView(request, response, status, model);
        return (modelAndView != null) ? modelAndView : new ModelAndView("error", model);
    }

    @RequestMapping
    public ResponseEntity<Map<String, Object>> error(HttpServletRequest request) {
        HttpStatus status = getStatus(request);
        if (status == HttpStatus.NO_CONTENT) {
            return new ResponseEntity<>(status);
        }
        Map<String, Object> body = getErrorAttributes(request, 
            getErrorAttributeOptions(request, MediaType.ALL));
        return new ResponseEntity<>(body, status);
    }
}

What BasicErrorController does:

Handles /error
If Accept: text/html → renders an HTML page (the Whitelabel Error Page)
If Accept: application/json → returns JSON

7.7.2. DefaultErrorAttributes — the Error Model

public class DefaultErrorAttributes implements ErrorAttributes {

    @Override
    public Map<String, Object> getErrorAttributes(WebRequest webRequest, 
            ErrorAttributeOptions options) {
        Map<String, Object> errorAttributes = new LinkedHashMap<>();
        errorAttributes.put("timestamp", new Date());
        addStatus(errorAttributes, webRequest);
        addErrorDetails(errorAttributes, webRequest, options);
        addPath(errorAttributes, webRequest, options);
        return errorAttributes;
    }
}

The standard JSON:

{
    "timestamp": "2026-09-23T12:00:00.000+00:00",
    "status": 500,
    "error": "Internal Server Error",
    "message": "...",
    "path": "/api/order"
}

7.7.3. ErrorPageCustomizer — Registering the Error Page

private static class ErrorPageCustomizer implements ErrorPageRegistrar, Ordered {

    @Override
    public void registerErrorPages(ErrorPageRegistry errorPageRegistry) {
        ErrorPage errorPage = new ErrorPage(
            this.dispatcherServletPath.getRelativePath(this.properties.getError().getPath()));
        errorPageRegistry.addErrorPages(errorPage);
    }
}

It registers /error as the error page in Tomcat. When Tomcat catches an unhandled exception (or a 404/405), it forwards the request to /error, where BasicErrorController produces the response.

The chain:

Controller → DispatcherServlet → HandlerExceptionResolver → not handled
    → Tomcat → forward to /error → BasicErrorController

7.8. Server Customization — ServerProperties

All the server.* settings are read into ServerProperties:

@ConfigurationProperties(prefix = "server", ignoreUnknownFields = true)
public class ServerProperties {
    private Integer port;
    private InetAddress address;
    private String contextPath;
    private final Servlet servlet = new Servlet();
    private final Tomcat tomcat = new Tomcat();
    private final Jetty jetty = new Jetty();
    // ...
}

Key settings:

Property	What it does
`server.port`	the port (8080 by default)
`server.address`	the address to listen on
`server.servlet.context-path`	the application's root path
`server.servlet.session.timeout`	session timeout
`server.tomcat.threads.max`	Tomcat's max threads
`server.tomcat.threads.min-spare`	min spare threads
`server.shutdown=graceful`	graceful shutdown
`spring.lifecycle.timeout-per-shutdown-phase`	graceful shutdown timeout

7.8.1. ServletWebServerFactoryCustomizer — Applying the Properties

public class ServletWebServerFactoryCustomizer 
        implements WebServerFactoryCustomizer<ConfigurableServletWebServerFactory>, Ordered {

    private final ServerProperties serverProperties;

    @Override
    public void customize(ConfigurableServletWebServerFactory factory) {
        PropertyMapper map = PropertyMapper.get().alwaysApplyingWhenNonNull();
        map.from(this.serverProperties::getPort).to(factory::setPort);
        map.from(this.serverProperties::getAddress).to(factory::setAddress);
        map.from(this.serverProperties.getServlet()::getContextPath).to(factory::setContextPath);
        map.from(this.serverProperties.getServlet()::getSession).to(factory::setSession);
        map.from(this.serverProperties::getSsl).to(factory::setSsl);
        map.from(this.serverProperties::getCompression).to(factory::setCompression);
        map.from(this.serverProperties::getHttp2).to(factory::setHttp2);
        map.from(this.serverProperties::getError).to(factory::setErrorPages);
    }

    @Override
    public int getOrder() {
        return 0;  // before user-defined customizers
    }
}

@Order(0) — auto-configured customizers run before user-defined ones. If you want to override a setting, declare your own WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> — it will run later and overwrite the value.

7.8.2. Your Own WebServerFactoryCustomizer

@Component
public class MyTomcatCustomizer 
        implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {

    @Override
    public void customize(TomcatServletWebServerFactory factory) {
        factory.addConnectorCustomizers(connector -> {
            connector.setProperty("maxKeepAliveRequests", "100");
        });
    }
}

7.9. The Reactive Stack — WebFlux and Netty

7.9.1. ReactiveWebServerFactoryAutoConfiguration

@AutoConfiguration
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)
@ConditionalOnClass(ReactiveHttpInputMessage.class)
@ConditionalOnWebApplication(type = Type.REACTIVE)
@EnableConfigurationProperties(ServerProperties.class)
@Import({ 
    ReactiveWebServerFactoryAutoConfiguration.BeanPostProcessorsRegistrar.class,
    ReactiveWebServerFactoryConfiguration.EmbeddedTomcat.class,
    ReactiveWebServerFactoryConfiguration.EmbeddedJetty.class,
    ReactiveWebServerFactoryConfiguration.EmbeddedUndertow.class,
    ReactiveWebServerFactoryConfiguration.EmbeddedNetty.class 
})
public class ReactiveWebServerFactoryAutoConfiguration {

    @Bean
    public ReactiveWebServerFactoryCustomizer reactiveWebServerFactoryCustomizer(
            ServerProperties serverProperties) {
        return new ReactiveWebServerFactoryCustomizer(serverProperties);
    }
}

EmbeddedNetty is activated via @ConditionalOnClass({ HttpServer.class, ... }) and creates a NettyReactiveWebServerFactory.

7.9.2. NettyReactiveWebServerFactory

public class NettyReactiveWebServerFactory extends AbstractReactiveWebServerFactory {

    @Override
    public WebServer getWebServer(HttpHandler httpHandler) {
        HttpServer httpServer = createHttpServer();
        // ... configuration
        return new NettyWebServer(httpServer, handler, 
            getRouteProvider(), this::getServerShutdownTimeout);
    }
}

The HttpHandler is built by WebHttpHandlerBuilder, which wires up WebFlux's DispatcherHandler. No Servlet API — Netty talks to the HttpHandler directly.

7.9.3. Key Differences from Servlet

Aspect	Servlet (Tomcat)	Reactive (Netty)
Model	Thread-per-request	Event loop
API	`ServletContext`, `HttpServletRequest`	`ServerHttpRequest`, `ServerHttpResponse`
Handler	`DispatcherServlet`	`DispatcherHandler`
Errors	`/error` + `BasicErrorController`	`DefaultErrorWebExceptionHandler`
Lifecycle	`WebServerStartStopLifecycle`	`NettyWebServer`

7.10. Spring Boot 3 vs Spring Boot 4 — Key Differences

7.10.1. Modularization

The biggest change. In Boot 3, everything lives in spring-boot-autoconfigure. In Boot 4, there are 47 modules:

Boot 3	Boot 4
`spring-boot-autoconfigure` (everything)	`spring-boot-webmvc` (MVC)
	`spring-boot-webflux` (WebFlux)
	`spring-boot-tomcat` (Tomcat)
	`spring-boot-jetty` (Jetty)
	`spring-boot-jackson` (Jackson)
`spring-boot-starter-web`	`spring-boot-starter-webmvc` (renamed)
`spring-boot-starter-webflux`	`spring-boot-starter-webflux` (unchanged)

The auto-configuration packages have moved too:

org.springframework.boot.autoconfigure.web.servlet → org.springframework.boot.webmvc.autoconfigure
org.springframework.boot.autoconfigure.web.reactive → org.springframework.boot.webflux.autoconfigure

7.10.2. Undertow Is Gone

Spring Boot 4 requires a Servlet 6.1 baseline, and Undertow isn't compatible with it. Undertow has been removed entirely:

"Spring Boot 4.0 requires a Servlet 6.1 baseline, with which Undertow is not yet compatible. As a result, Undertow support is dropped, including the Undertow starter and the ability to use Undertow as an embedded server."

What remains: Tomcat, Jetty, and Netty (for WebFlux).

7.10.3. Class Relocations

The embedded server classes have moved:

Boot 3	Boot 4
`org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory`	`org.springframework.boot.tomcat.TomcatServletWebServerFactory`
`org.springframework.boot.web.embedded.netty.NettyReactiveWebServerFactory`	`org.springframework.boot.netty.NettyReactiveWebServerFactory`

7.10.4. What Hasn't Changed

The ServletWebServerFactory mechanism — the same abstraction.
ServletContextInitializer — the same SPI.
ErrorMvcAutoConfiguration / BasicErrorController — the same logic.
WebMvcAutoConfiguration — the same beans, just in different packages.
WebServerFactoryCustomizer — the same interface.

7.11. Diagram: Creating the Web Server (Servlet)

refresh()
  └─ AbstractApplicationContext.refresh()
        ├─ ...
        └─ onRefresh()                          ← overridden in ServletWebServerApplicationContext
              │
              └─ createWebServer()
                    ├─ getWebServerFactory()
                    │     └─ TomcatServletWebServerFactory (from ServletWebServerFactoryAutoConfiguration)
                    │
                    ├─ factory.getWebServer(getSelfInitializer())
                    │     └─ TomcatServletWebServerFactory.getWebServer()
                    │           ├─ new Tomcat()
                    │           ├─ context = tomcat.addContext()
                    │           ├─ initializer.onStartup(servletContext)   ← the callback
                    │           │     └─ ServletContextInitializerBeans
                    │           │           ├─ DispatcherServletRegistrationBean
                    │           │           ├─ FilterRegistrationBean
                    │           │           └─ ServletListenerRegistrationBean
                    │           └─ return new TomcatWebServer(tomcat)
                    │
                    ├─ registerSingleton("webServerStartStop", 
                    │     new WebServerStartStopLifecycle(...))
                    │
                    └─ registerSingleton("webServerGracefulShutdown", 
                          new WebServerGracefulShutdownLifecycle(...))
        │
        └─ finishRefresh()
              └─ lifecycleProcessor.onRefresh()
                    └─ WebServerStartStopLifecycle.start()    ← phase = MAX-1
                          ├─ tomcat.start()
                          ├─ publishEvent(ServletWebServerInitializedEvent)
                          └─ running = true

7.12. Key Takeaways

ServletWebServerFactoryAutoConfiguration picks Tomcat/Jetty/Undertow from the classpath. @AutoConfigureOrder(HIGHEST_PRECEDENCE).
onRefresh() → createWebServer() is where the server is born. It runs inside refresh(), before finishRefresh().
ServletContextInitializer is the SPI for registering servlets, filters, and listeners. DispatcherServletRegistrationBean is one of its implementations.
WebServerStartStopLifecycle is a SmartLifecycle with phase = MAX-1 — it starts Tomcat after all the other beans.
DispatcherServletAutoConfiguration creates the DispatcherServlet and its registration. Ordered after ServletWebServerFactoryAutoConfiguration.
WebMvcAutoConfiguration wires up MVC: HandlerMapping, HandlerAdapter, HttpMessageConverters. Opt out via @EnableWebMvc.
ErrorMvcAutoConfiguration — /error + BasicErrorController. This isn't MVC; it's a Boot add-on.
ServletWebServerFactoryCustomizer applies the server.* properties. @Order(0) — user-defined customizers run after it.
The reactive stack: NettyReactiveWebServerFactory + DispatcherHandler. A different model, different APIs. 10 Boot 4: modularization (47 modules), spring-boot-starter-webmvc, Undertow removed, packages relocated. The mechanism itself — unchanged.

Spring Boot Under the Hood. Part 6: Bean Lifecycle — Born, Post-Processed, Destroyed

Silver_dev — Wed, 23 Sep 2026 22:15:48 +0000

By this point we have:

A fully built ApplicationContext (Part 3)
BeanDefinitions registered by scanning (Part 4)
Auto-configurations loaded (Part 5)

Now refresh() has to turn all those BeanDefinitions into living objects — beans. Let's go through it step by step.

6.1. BeanDefinition — the Bean's Blueprint

Before we talk about the lifecycle, we need to understand what a BeanDefinition is.

public interface BeanDefinition extends AttributeAccessor, BeanMetadataElement {
    String getBeanClassName();
    String getScope();
    boolean isLazyInit();
    boolean isPrimary();
    String[] getDependsOn();
    boolean isAutowireCandidate();
    ConstructorArgumentValues getConstructorArgumentValues();
    MutablePropertyValues getPropertyValues();
    String getInitMethodName();
    String getDestroyMethodName();
    int getRole();
    // ...
}

A BeanDefinition is metadata about a bean, not the bean itself. From it, Spring learns:

Which class to instantiate
Which scope (singleton / prototype / request / session)
What to inject (constructor args / property values)
Which init/destroy method to call
Whether it's lazy or not

The implementation hierarchy:

Class	When it's used
`RootBeanDefinition`	The main implementation (the merge result)
`ChildBeanDefinition`	Legacy, for parent-child definitions
`GenericBeanDefinition`	The modern one (used in configurations)
`AnnotatedGenericBeanDefinition`	For annotated classes (`@Configuration`, `@Component`)
`ScannedGenericBeanDefinition`	For classes found by scanning
`ConfigurationClassBeanDefinition`	For `@Bean` methods

A key feature: a BeanDefinition can act as a parent for other BeanDefinitions. When creating a bean, Spring performs a merge — combining parent and child into a RootBeanDefinition. This is called a MergedBeanDefinition.

6.2. The Full Bean Lifecycle — an Overview

Here is the complete scheme. We'll break down every step:

1.  BeanDefinition registered (scanning / @Bean / .imports)
2.  BeanFactoryPostProcessor.postProcessBeanFactory()
3.  BeanPostProcessor registration
4.  getBean() is called
5.  ─── for singletons ───
6.  MergedBeanDefinition is created (parent/child merge)
7.  InstantiationAwareBeanPostProcessor.postProcessBeforeInstantiation()
8.  InstantiationAwareBeanPostProcessor.determineCandidateConstructors()
9.  Constructor invoked (or factory method)
10. MergedBeanDefinitionPostProcessor.postProcessMergedBeanDefinition()
11. InstantiationAwareBeanPostProcessor.postProcessAfterInstantiation()
12. InstantiationAwareBeanPostProcessor.postProcessProperties()
       └─ @Autowired / @Value / @Resource
13. Aware interfaces: BeanNameAware, BeanClassLoaderAware, BeanFactoryAware
       └─ ApplicationContextAware, EnvironmentAware, ...
14. BeanPostProcessor.postProcessBeforeInitialization()
       └─ @PostConstruct (CommonAnnotationBeanPostProcessor)
15. InitializingBean.afterPropertiesSet()
16. @Bean(initMethod="...")
17. BeanPostProcessor.postProcessAfterInitialization()
       └─ AOP proxy goes here (AbstractAutoProxyCreator)
18. ─── singleton cache ───
19. Bean ready to use
20. ─── at shutdown ───
21. DestructionAwareBeanPostProcessor.postProcessBeforeDestruction()
       └─ @PreDestroy
22. DisposableBean.destroy()
23. @Bean(destroyMethod="...")

6.3. BeanFactoryPostProcessor — Working with Metadata

This is the first stage. A BeanFactoryPostProcessor (BFPP) works with BeanDefinitions — before any beans are created.

@FunctionalInterface
public interface BeanFactoryPostProcessor {
    void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory);
}

It's invoked by AbstractApplicationContext.invokeBeanFactoryPostProcessors(). The order:

BeanDefinitionRegistryPostProcessor.postProcessBeanDefinitionRegistry() — registers new BeanDefinitions
BeanFactoryPostProcessor.postProcessBeanFactory() — modifies existing ones

The main BFPP in Spring is ConfigurationClassPostProcessor. It:

Processes @Configuration, @Bean, @ComponentScan, @Import, @EnableAutoConfiguration
Registers BeanDefinitions for all the beans it finds

This is where Parts 3–4 take place. ConfigurationClassPostProcessor has the highest precedence (Ordered.HIGHEST_PRECEDENCE), so it runs first.

Your own BFPP:

public class MyBeanFactoryPostProcessor implements BeanFactoryPostProcessor {
    @Override
    public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) {
        BeanDefinition bd = beanFactory.getBeanDefinition("myService");
        bd.setScope(BeanDefinition.SCOPE_PROTOTYPE);
    }
}

Registration: @Component or a @Bean method. Don't inject other beans into it — at this stage they don't exist yet.

6.4. BeanPostProcessor — Working with Beans

A BeanPostProcessor (BPP) is invoked for every bean as it's being created.

public interface BeanPostProcessor {
    default Object postProcessBeforeInitialization(Object bean, String beanName) {
        return bean;
    }
    default Object postProcessAfterInitialization(Object bean, String beanName) {
        return bean;
    }
}

Two methods — before and after initialization. This is where all of Spring's magic is built: @Autowired, @PostConstruct, AOP proxies, @Transactional.

The BPP hierarchy

BeanPostProcessor
  ├─ InstantiationAwareBeanPostProcessor
  │     ├─ postProcessBeforeInstantiation()  ← before the bean is created
  │     ├─ postProcessAfterInstantiation()   ← after creation, before injection
  │     └─ postProcessProperties()           ← dependency injection
  │
  ├─ SmartInstantiationAwareBeanPostProcessor
  │     └─ determineCandidateConstructors()  ← constructor selection
  │
  ├─ MergedBeanDefinitionPostProcessor
  │     └─ postProcessMergedBeanDefinition() ← collecting metadata for injection
  │
  └─ DestructionAwareBeanPostProcessor
        └─ postProcessBeforeDestruction()    ← @PreDestroy

Built-in Spring BPPs

BPP	What it does	Order
`AutowiredAnnotationBeanPostProcessor`	`@Autowired`, `@Value`, `@Inject`	`Ordered.LOWEST_PRECEDENCE - 2`
`CommonAnnotationBeanPostProcessor`	`@PostConstruct`, `@PreDestroy`, `@Resource`	`Ordered.LOWEST_PRECEDENCE - 3`
`ConfigurationPropertiesBindingPostProcessor`	`@ConfigurationProperties`	`Ordered.HIGHEST_PRECEDENCE + 1`
`ApplicationListenerDetector`	Registers `ApplicationListener` beans	`LOWEST_PRECEDENCE`
`AbstractAutoProxyCreator`	AOP proxies (`@Transactional`, `@Async`, `@Cacheable`)	depends on the implementation

Important: BPP ordering is critical. For example, @PostConstruct must run before AOP proxying — otherwise the @PostConstruct method would be invoked on the proxy, not on the target object.

6.5. Bean Creation — a Step-by-Step Breakdown

Let's walk through doCreateBean() from AbstractAutowireCapableBeanFactory — the central bean-creation method.

Step 1: `createBean()` — the entry point

@Override
protected Object createBean(String beanName, RootBeanDefinition mbd, Object[] args) {
    // 1. Give BPPs a chance to return a proxy instead of the real bean
    Object bean = resolveBeforeInstantiation(beanName, mbdToUse);
    if (bean != null) {
        return bean;
    }

    // 2. Actual creation
    return doCreateBean(beanName, mbdToUse, args);
}

Step 2: `resolveBeforeInstantiation()` — the early proxy

protected Object resolveBeforeInstantiation(String beanName, RootBeanDefinition mbd) {
    Object bean = null;
    if (!Boolean.FALSE.equals(mbd.beforeInstantiationResolved)) {
        if (!mbd.isSynthetic() && hasInstantiationAwareBeanPostProcessors()) {
            Class<?> targetType = determineTargetType(beanName, mbd);
            bean = applyBeanPostProcessorsBeforeInstantiation(targetType, beanName);
            if (bean != null) {
                bean = applyBeanPostProcessorsAfterInitialization(bean, beanName);
            }
        }
    }
    return bean;
}

InstantiationAwareBeanPostProcessor.postProcessBeforeInstantiation() can return a ready-made object — in which case the regular creation cycle is skipped entirely. This is used, for example, for @Configuration proxies and in some AOP scenarios.

Step 3: doCreateBean() — the core logic

protected Object doCreateBean(String beanName, RootBeanDefinition mbd, Object[] args) {
    // 1. Instantiate (constructor / factory method)
    BeanWrapper instanceWrapper = null;
    if (mbd.isSingleton()) {
        instanceWrapper = this.factoryBeanInstanceCache.remove(beanName);
    }
    if (instanceWrapper == null) {
        instanceWrapper = createBeanInstance(beanName, mbd, args);
    }
    Object bean = instanceWrapper.getWrappedInstance();

    // 2. MergedBeanDefinitionPostProcessor
    applyMergedBeanDefinitionPostProcessors(mbd, beanType, beanName);

    // 3. Early registration (for circular dependencies)
    boolean earlySingletonExposure = (mbd.isSingleton() && this.allowCircularReferences 
        && isSingletonCurrentlyInCreation(beanName));
    if (earlySingletonExposure) {
        addSingletonFactory(beanName, () -> getEarlyBeanReference(beanName, mbd, bean));
    }

    // 4. Populate — inject dependencies
    Object exposedObject = bean;
    populateBean(beanName, mbd, instanceWrapper);

    // 5. Initialize
    exposedObject = initializeBean(beanName, exposedObject, mbd);

    // 6. Circular dependency check
    if (earlySingletonExposure) {
        Object earlySingletonReference = getSingleton(beanName, false);
        // ...
    }

    return exposedObject;
}

Step 4: `createBeanInstance()` — choosing the constructor

protected BeanWrapper createBeanInstance(String beanName, RootBeanDefinition mbd, Object[] args) {
    // 1. If there's a factory method — use it
    if (mbd.getFactoryMethodName() != null) {
        return instantiateUsingFactoryMethod(beanName, mbd, args);
    }

    // 2. Determine the constructor
    Constructor<?>[] ctors = determineConstructorsFromBeanPostProcessors(beanClass, beanName);
    if (ctors != null || mbd.getResolvedAutowireMode() == AUTOWIRE_CONSTRUCTOR 
            || mbd.hasConstructorArgumentValues() || !ObjectUtils.isEmpty(args)) {
        return autowireConstructor(beanName, mbd, ctors, args);
    }

    // 3. The default constructor
    return instantiateBean(beanName, mbd);
}

determineConstructorsFromBeanPostProcessors() calls SmartInstantiationAwareBeanPostProcessor.determineCandidateConstructors(). This is where AutowiredAnnotationBeanPostProcessor finds the @Autowired constructor (or the single constructor).

Step 5: `populateBean()` — injecting dependencies

protected void populateBean(String beanName, RootBeanDefinition mbd, BeanWrapper bw) {
    // 1. postProcessAfterInstantiation — a BPP can veto injection
    if (!mbd.isSynthetic() && hasInstantiationAwareBeanPostProcessors()) {
        for (InstantiationAwareBeanPostProcessor bp : getBeanPostProcessorCache().instantiationAware) {
            if (!bp.postProcessAfterInstantiation(bw.getWrappedInstance(), beanName)) {
                return;
            }
        }
    }

    // 2. postProcessProperties — the injection itself
    PropertyValues pvs = (mbd.hasPropertyValues() ? mbd.getPropertyValues() : null);
    if (pvs != null || hasInstantiationAwareBeanPostProcessors()) {
        for (InstantiationAwareBeanPostProcessor bp : getBeanPostProcessorCache().instantiationAware) {
            PropertyValues pvsToUse = bp.postProcessProperties(pvs, bw.getWrappedInstance(), beanName);
            // ...
        }
    }

    // 3. applyPropertyValues — setting values (for XML configs)
    if (pvs != null) {
        applyPropertyValues(beanName, mbd, bw, pvs);
    }
}

This is where AutowiredAnnotationBeanPostProcessor.postProcessProperties() finds @Autowired fields and setters and injects them.

Step 6: `initializeBean()` — initialization

protected Object initializeBean(String beanName, Object bean, RootBeanDefinition mbd) {
    // 1. Aware interfaces
    invokeAwareMethods(beanName, bean);   // BeanNameAware, BeanClassLoaderAware, BeanFactoryAware

    // 2. postProcessBeforeInitialization
    Object wrappedBean = bean;
    if (mbd == null || !mbd.isSynthetic()) {
        wrappedBean = applyBeanPostProcessorsBeforeInitialization(wrappedBean, beanName);
    }

    // 3. init-method
    try {
        invokeInitMethods(beanName, wrappedBean, mbd);
    } catch (Throwable ex) {
        throw new BeanCreationException(...);
    }

    // 4. postProcessAfterInitialization
    if (mbd == null || !mbd.isSynthetic()) {
        wrappedBean = applyBeanPostProcessorsAfterInitialization(wrappedBean, beanName);
    }

    return wrappedBean;
}

invokeAwareMethods()

private void invokeAwareMethods(String beanName, Object bean) {
    if (bean instanceof Aware) {
        if (bean instanceof BeanNameAware bna) {
            bna.setBeanName(beanName);
        }
        if (bean instanceof BeanClassLoaderAware bcla) {
            ClassLoader bcl = getBeanClassLoader();
            if (bcl != null) bcla.setBeanClassLoader(bcl);
        }
        if (bean instanceof BeanFactoryAware bfa) {
            bfa.setBeanFactory(this);
        }
    }
}

These are only three of the Aware interfaces. The rest (ApplicationContextAware, EnvironmentAware, ResourceLoaderAware, ApplicationEventPublisherAware, MessageSourceAware) are handled by ApplicationContextAwareProcessor — a BeanPostProcessor registered by the context.

applyBeanPostProcessorsBeforeInitialization()

This is where CommonAnnotationBeanPostProcessor.postProcessBeforeInitialization() runs — the one that invokes @PostConstruct methods.

The ordering of multiple BPPs follows @Order / Ordered. CommonAnnotationBeanPostProcessor has Ordered.LOWEST_PRECEDENCE - 3, so @PostConstruct runs later than other beforeInitialization callbacks but earlier than AOP proxying (which happens in afterInitialization).

invokeInitMethods()

protected void invokeInitMethods(String beanName, Object bean, RootBeanDefinition mbd) {
    boolean isInitializingBean = (bean instanceof InitializingBean);
    if (isInitializingBean && (mbd == null || !mbd.hasAnyExternallyManagedInitMethod("afterPropertiesSet"))) {
        ((InitializingBean) bean).afterPropertiesSet();
    }
    if (mbd != null && bean.getClass() != NullBean.class) {
        String initMethodName = mbd.getInitMethodName();
        if (StringUtils.hasLength(initMethodName) 
                && !(isInitializingBean && "afterPropertiesSet".equals(initMethodName))
                && !mbd.hasAnyExternallyManagedInitMethod(initMethodName)) {
            invokeCustomInitMethod(beanName, bean, mbd);
        }
    }
}

The order: InitializingBean.afterPropertiesSet() → @Bean(initMethod=...). @PostConstruct was already invoked earlier, in postProcessBeforeInitialization.

The final initialization order:

@PostConstruct
InitializingBean.afterPropertiesSet()
@Bean(initMethod = "...")

applyBeanPostProcessorsAfterInitialization()

This is where the AOP proxy is created. AbstractAutoProxyCreator.postProcessAfterInitialization() checks whether the bean carries @Transactional, @Async, @Cacheable, etc., and if so, wraps it in a proxy (CGLIB or a JDK dynamic proxy).

Key point: after afterInitialization, it's the proxy — not the original object — that goes into the singleton cache. All subsequent @Autowired injections will receive the proxy.

6.6. Call Order — a Summary Table

For a MyService bean with the full set of callbacks:

#	Callback	Invoked by
1	Constructor	`createBeanInstance()`
2	`@Autowired` fields/setters	`AutowiredAnnotationBeanPostProcessor`
3	`BeanNameAware.setBeanName()`	`invokeAwareMethods()`
4	`BeanFactoryAware.setBeanFactory()`	`invokeAwareMethods()`
5	`ApplicationContextAware.setApplicationContext()`	`ApplicationContextAwareProcessor`
6	`@PostConstruct`	`CommonAnnotationBeanPostProcessor`
7	`InitializingBean.afterPropertiesSet()`	`invokeInitMethods()`
8	`@Bean(initMethod)`	`invokeInitMethods()`
9	AOP proxy	`AbstractAutoProxyCreator`
10	Bean ready	Singleton cache
11	`@PreDestroy`	`CommonAnnotationBeanPostProcessor`
12	`DisposableBean.destroy()`	`DisposableBeanAdapter`
13	`@Bean(destroyMethod)`	`DisposableBeanAdapter`

6.7. Circular Dependencies

The problem:

A → B → A

If A needs B and B needs A — the classic deadlock.

Spring's solution: the three-level cache.

public class DefaultSingletonBeanRegistry {
    // Level 1: fully initialized singleton beans
    private final Map<String, Object> singletonObjects = new ConcurrentHashMap<>(256);

    // Level 2: early singletons (before populate/init)
    private final Map<String, Object> earlySingletonObjects = new ConcurrentHashMap<>(16);

    // Level 3: singleton factories (lambdas producing early references)
    private final Map<String, ObjectFactory<?>> singletonFactories = new HashMap<>(16);
}

The getSingleton() algorithm:

Check singletonObjects → if present, return it.
Check earlySingletonObjects → if present, return it.
Check singletonFactories → if present, invoke the factory, put the result into earlySingletonObjects, return it.
Otherwise — create the bean.

An example:

We start creating A → put an ObjectFactory into level 3.
Injecting B into A → we start creating B.
B needs A → getSingleton("A") → level 3 → early reference → returns the half-finished A.
B finishes initializing completely.
We resume initializing A → A is ready.

Limitations:

Works for singletons only.
Doesn't work with constructor injection — neither bean can be fully created through a constructor, because the constructor runs before the bean is registered in the cache. The fix: @Lazy on one of the parameters.
Spring Boot 2.6+ bans circular references by default. Re-enable via spring.main.allow-circular-references=true.

6.8. @lazy — Deferred Initialization

@Service
public class A {
    @Autowired
    @Lazy
    private B b;
}

Spring injects a proxy for B; the real bean is created on first access. This sidesteps circular dependencies.

@Lazy on a @Configuration class makes the entire configuration lazy. @Lazy on a @Bean method makes that bean lazy.

6.9. ObjectProvider and @Lookup

ObjectProvider

@Service
public class MyService {
    @Autowired
    private ObjectProvider<PrototypeBean> prototypeBeanProvider;

    public void doWork() {
        PrototypeBean bean = prototypeBeanProvider.getObject();  // a new one every time
    }
}

An ObjectProvider is a lazy resolver. getObject() asks the container for the bean every time. It works for the prototype scope too.

@Lookup

@Service
public abstract class MyService {
    @Lookup
    protected abstract PrototypeBean createPrototypeBean();
}

Spring generates a subclass (CGLIB) that overrides the method and asks the container for the bean. An older approach — ObjectProvider is preferred.

6.10. Bean Destruction

registerShutdownHook()

Called from SpringApplication.refreshContext():

private void refreshContext(ConfigurableApplicationContext context) {
    if (this.registerShutdownHook) {
        try {
            context.registerShutdownHook();
        } catch (AccessControlException ex) { }
    }
    refresh(context);
}

registerShutdownHook() adds a JVM shutdown hook that will call context.close() when the JVM terminates.

close() → doClose()

protected void doClose() {
    // 1. LifecycleProcessor.onClose() — stops Lifecycle beans
    if (this.lifecycleProcessor != null) {
        this.lifecycleProcessor.onClose();
    }

    // 2. Destroy the beans
    destroyBeans();

    // 3. Close the BeanFactory
    closeBeanFactory();

    // 4. onClose()
    onClose();

    // 5. Reset the listeners
    if (this.earlyApplicationListeners != null) {
        this.applicationListeners.clear();
        this.applicationListeners.addAll(this.earlyApplicationListeners);
    }

    // 6. active = false
    this.active.set(false);
}

destroyBeans() → destroySingleton()

public void destroySingleton(String beanName) {
    removeSingleton(beanName);
    DisposableBean disposableBean = this.disposableBeans.remove(beanName);
    if (disposableBean != null) {
        disposableBean.destroy();
    }
}

DisposableBeanAdapter.destroy() calls, in order:

DestructionAwareBeanPostProcessor.postProcessBeforeDestruction() → @PreDestroy
DisposableBean.destroy()
@Bean(destroyMethod) or AutoCloseable.close()

Important: Spring automatically calls close() on beans implementing AutoCloseable / Closeable unless you say otherwise. Disable it via @Bean(destroyMethod = "").

6.11. SmartLifecycle and Lifecycle

Lifecycle is an interface for beans with start/stop phases:

public interface Lifecycle {
    void start();
    void stop();
    boolean isRunning();
}

SmartLifecycle extends it:

public interface SmartLifecycle extends Lifecycle, Phased {
    boolean isAutoStartup();
    void stop(Runnable callback);
    int getPhase();
}

The LifecycleProcessor (by default, DefaultLifecycleProcessor) drives:

onRefresh() — calls start() on all beans with isAutoStartup(), ordered by getPhase() (ascending)
onClose() — calls stop() on all of them, in descending getPhase() order

Example: WebServerStartStopLifecycle — starts/stops Tomcat.

6.12. Spring Boot 3 vs Spring Boot 4

Aspect	Spring Boot 3	Spring Boot 4
Bean lifecycle	Unchanged	Unchanged
BeanPostProcessor	The same interfaces	The same interfaces
Circular references	Banned by default (since 2.6)	Banned
AOT	Present, but opt-in	More aggressive, reflection-free by default
`@ConstructorBinding`	Optional	Legacy
`BeanRegistrar`	Introduced in Spring Framework 7	The primary registration approach for AOT

With AOT (Boot 3.x / 4.x), Spring generates code that registers BeanDefinitions programmatically, without reflection. @PostConstruct, @Autowired, and other callbacks turn into direct code calls. It's faster and compatible with GraalVM native images.

6.13. Diagram: the Complete Bean Lifecycle

BeanDefinition
    │
    ▼
BeanFactoryPostProcessor.postProcessBeanFactory()   ← works with metadata
    │
    ▼
BeanPostProcessors registered in the context
    │
    ▼
getBean(beanName)
    │
    ├─ in singletonObjects?  → yes → return (already built)
    │
    ▼
createBean()
    │
    ├─ resolveBeforeInstantiation()
    │     └─ InstantiationAwareBeanPostProcessor.postProcessBeforeInstantiation()
    │           └─ if it returned an object → return (shortcut)
    │
    ▼
doCreateBean()
    │
    ├─ 1. createBeanInstance()
    │       ├─ determineCandidateConstructors()    ← the @Autowired constructor
    │       └─ new Instance() / factory method
    │
    ├─ 2. applyMergedBeanDefinitionPostProcessors()
    │       └─ @Autowired metadata is collected
    │
    ├─ 3. addSingletonFactory()                    ← early cache (for circulars)
    │
    ├─ 4. populateBean()
    │       ├─ postProcessAfterInstantiation()
    │       └─ postProcessProperties()             ← @Autowired / @Value
    │
    ├─ 5. initializeBean()
    │       ├─ invokeAwareMethods()                ← BeanNameAware, BeanFactoryAware
    │       ├─ postProcessBeforeInitialization()
    │       │     ├─ ApplicationContextAwareProcessor
    │       │     └─ CommonAnnotationBeanPostProcessor → @PostConstruct
    │       ├─ invokeInitMethods()
    │       │     ├─ InitializingBean.afterPropertiesSet()
    │       │     └─ @Bean(initMethod)
    │       └─ postProcessAfterInitialization()
    │             └─ AbstractAutoProxyCreator → AOP proxy
    │
    ├─ 6. addSingleton()                           ← the finished bean goes into the cache
    │
    ▼
Bean ready
    │
    ▼ (at shutdown)
destroySingleton()
    ├─ DestructionAwareBeanPostProcessor.postProcessBeforeDestruction()
    │     └─ @PreDestroy
    ├─ DisposableBean.destroy()
    └─ @Bean(destroyMethod) / AutoCloseable.close()

6.14. Key Takeaways

A BeanDefinition is metadata, not a bean. From it, Spring learns everything about the future object.
A BeanFactoryPostProcessor works with metadata before beans are created. The main BFPP is ConfigurationClassPostProcessor.
A BeanPostProcessor works with beans. Every bean passes through the BPP chain.
The initialization order: @PostConstruct → InitializingBean.afterPropertiesSet() → @Bean(initMethod).
The AOP proxy is created in postProcessAfterInitialization(). After that, the singleton cache holds the proxy, not the original.
Circular dependencies are resolved via the three-level cache — but only for singletons and never for constructor injection.
@Lazy and ObjectProvider are the ways around circular dependencies.
Destruction: @PreDestroy → DisposableBean.destroy() → @Bean(destroyMethod) → AutoCloseable.close().
SmartLifecycle is for beans with start/stop phases (e.g., the web server).
Boot 4 + AOT: the lifecycle turns into generated code, reflection is minimized.

Spring Boot Under the Hood. Part 5: The Heart of Spring Boot — How Auto-configuration Works

Silver_dev — Wed, 23 Sep 2026 18:40:26 +0000

Auto-configuration is the heart of Spring Boot. It's what lets you add spring-boot-starter-web to your pom.xml and instantly get Tomcat, DispatcherServlet, Jackson, and a bunch of other beans — without a single line of configuration.

Let's break down how it works, down to the last detail.

5.1. Where the Entry Point Lives

You already know that @SpringBootApplication includes @EnableAutoConfiguration. Let's look at it:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Inherited
@AutoConfigurationPackage
@Import(AutoConfigurationImportSelector.class)
public @interface EnableAutoConfiguration {
    Class<?>[] exclude() default {};
    String[] excludeName() default {};
}

Two key points:

@AutoConfigurationPackage — remembers the main class's package (we covered this in Part 4).
@Import(AutoConfigurationImportSelector.class) — imports the selector that does all the magic.

@Import is a Spring Framework mechanism that lets you add BeanDefinitions to the context programmatically, bypassing scanning. A selector implements ImportSelector and returns an array of class names to register.

5.2. AutoConfigurationImportSelector — the Master Conductor

public class AutoConfigurationImportSelector 
        implements DeferredImportSelector, BeanClassLoaderAware, 
                   ResourceLoaderAware, BeanFactoryAware, EnvironmentAware, Ordered {

Note: this is a DeferredImportSelector, not a plain ImportSelector. The difference is fundamental.

5.2.1. DeferredImportSelector vs ImportSelector

Type	When it's processed
`ImportSelector`	Immediately, while parsing `@Configuration`
`DeferredImportSelector`	After all regular `@Configuration` classes have been processed

This guarantees that auto-configurations are processed after user-defined beans. That's exactly why @ConditionalOnMissingBean in auto-configurations works correctly — by the time they're processed, all of your @Bean methods are already registered.

5.2.2. selectImports() — the entry point

@Override
public String[] selectImports(AnnotationMetadata importingClassMetadata) {
    AutoConfigurationEntry autoConfigurationEntry = 
        getAutoConfigurationEntry(annotationMetadata);
    return StringUtils.toStringArray(autoConfigurationEntry.getConfigurations());
}

The getAutoConfigurationEntry() method is the central one. Let's break it down.

5.3. getAutoConfigurationEntry() — a Step-by-Step Breakdown

protected AutoConfigurationEntry getAutoConfigurationEntry(
        AnnotationMetadata annotationMetadata) {

    // 1. Check: is auto-configuration enabled at all?
    if (!isEnabled(annotationMetadata)) {
        return EMPTY_ENTRY;
    }

    // 2. Get the @EnableAutoConfiguration attributes (exclude, excludeName)
    AnnotationAttributes attributes = getAttributes(annotationMetadata);

    // 3. Load ALL candidates from the classpath
    List<String> configurations = getCandidateConfigurations(
        annotationMetadata, attributes);

    // 4. Deduplicate
    configurations = removeDuplicates(configurations);

    // 5. Apply exclusions
    Set<String> exclusions = getExclusions(annotationMetadata, attributes);
    checkExcludedClasses(configurations, exclusions);
    configurations.removeAll(exclusions);

    // 6. Filter by conditions (ConfigurationClassFilter)
    configurations = getConfigurationClassFilter().filter(configurations);

    // 7. Publish the AutoConfigurationImportEvent
    fireAutoConfigurationImportEvents(configurations, exclusions);

    return new AutoConfigurationEntry(configurations, exclusions);
}

The key steps are 3 and 6.

5.4. Loading the Candidates — .imports Instead of spring.factories

5.4.1. A Bit of History

Version	Mechanism
Spring Boot 1.x – 2.6	`META-INF/spring.factories` (the EnableAutoConfiguration key)
Spring Boot 2.7	Both mechanisms in parallel (backward compatibility)
Spring Boot 3.0+	`.imports` only; `spring.factories` registration for auto-configurations removed

This is confirmed by the official documentation and release notes: "Spring Boot 2.7 introduced a new META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports file for registering auto-configurations, while maintaining backwards compatibility with registration in spring.factories. With this release, support for registering auto-configurations in spring.factories has been removed in favor of the imports file."

5.4.2. What the .imports File Looks Like

The file path:

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

The format — one line = one class:

org.springframework.boot.autoconfigure.admin.SpringApplicationAdminJmxAutoConfiguration
org.springframework.boot.autoconfigure.aop.AopAutoConfiguration
org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration
org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration
...

For comparison, the old spring.factories used a key-value format:

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
org.springframework.boot.autoconfigure.aop.AopAutoConfiguration,\
org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration

The advantages of .imports: simpler parsing, no escaping issues, better AOT compatibility.

5.4.3. ImportCandidates — the loader

Candidates are loaded via ImportCandidates.load():

public static ImportCandidates load(Class<?> annotation, ClassLoader classLoader) {
    String location = String.format(
        "META-INF/spring/%s.imports", annotation.getName());
    List<String> candidates = new ArrayList<>();
    // ... reads all files at this location from all JARs
    return new ImportCandidates(candidates);
}

Key point: ImportCandidates does not use SpringFactoriesLoader (which reads spring.factories). It's a separate mechanism optimized for AOT and native images.

5.4.4. @AutoConfiguration — the new annotation

Since Spring Boot 2.7, auto-configuration classes are marked with @AutoConfiguration instead of @Configuration:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Configuration(proxyBeanMethods = false)
@AutoConfigureBefore
@AutoConfigureAfter
public @interface AutoConfiguration {
    @AliasFor(annotation = AutoConfigureBefore.class, attribute = "value")
    Class<?>[] before() default {};

    @AliasFor(annotation = AutoConfigureAfter.class, attribute = "value")
    Class<?>[] after() default {};
}

Three key differences from @Configuration:

proxyBeanMethods = false — auto-configurations are not proxied with CGLIB. It's faster and avoids circular dependencies.
It carries @AutoConfigureBefore / @AutoConfigureAfter — the ordering can be specified right in the annotation.
It's semantically separated from user-defined @Configuration classes.

5.5. Conditional Annotations (@Conditional*) — Filtering the Candidates

After all the candidates are loaded (there are 150+ of them in Spring Boot 3.x), filtering begins. This is where the conditional annotations come into play.

5.5.1. How It's Wired

The filtering happens in ConfigurationClassFilter:

class ConfigurationClassFilter {
    private final List<AutoConfigurationImportFilter> filters;

    List<String> filter(List<String> configurations) {
        String[] candidates = configurations.toArray(new String[0]);
        boolean[] skip = new boolean[candidates.length];
        boolean skipped = false;
        for (AutoConfigurationImportFilter filter : this.filters) {
            boolean[] match = filter.match(candidates, this.autoConfigurationMetadata);
            for (int i = 0; i < match.length; i++) {
                if (!match[i]) {
                    skip[i] = true;
                    skipped = true;
                }
            }
        }
        // ... returns the filtered list
    }
}

AutoConfigurationImportFilter is an SPI interface whose implementations are loaded via spring.factories (yes, spring.factories is still used for internal SPIs — just not for auto-configuration registration). Spring Boot ships three filters:

Filter	What it checks
`OnClassCondition`	`@ConditionalOnClass` / `@ConditionalOnMissingClass`
`OnBeanCondition`	`@ConditionalOnBean` / `@ConditionalOnMissingBean`
`OnWebApplicationCondition`	`@ConditionalOnWebApplication` / `@ConditionalOnNotWebApplication`

Important: this is the first stage of filtering — a coarse-grained pass. It only checks for the presence of classes and beans, without loading the auto-configurations themselves. Finer-grained checks (properties, resources, expressions) happen later, when ConfigurationClassParser processes each specific class.

5.5.2. The Main Conditional Annotations

@ConditionalOnClass / @ConditionalOnMissingClass

@AutoConfiguration
@ConditionalOnClass(DataSource.class)   // activates only if DataSource is on the classpath
public class DataSourceAutoConfiguration { }

The check happens via ASM — the class is not loaded into the JVM; only the .class file's metadata is read. That's why it's safe to reference classes that may not be present at runtime.

@ConditionalOnBean / @ConditionalOnMissingBean

@Bean
@ConditionalOnMissingBean
public DataSource dataSource() {
    return new HikariDataSource();
}

The key customization mechanism. If you've declared your own DataSource, the auto-configuration backs off and doesn't create its own. This is exactly why auto-configurations are processed as a DeferredImportSelector — so that all of your beans are already registered by the time the checks run.

Caveat: @ConditionalOnMissingBean only works reliably for @Bean methods and @Configuration classes that are processed after yours. If you put it on a regular @Configuration, the result can be unpredictable — @conditionals are evaluated while parsing the @Configuration, and the parsing order may differ from the bean registration order.

@ConditionalOnProperty

@AutoConfiguration
@ConditionalOnProperty(
    prefix = "spring.datasource", 
    name = "url", 
    matchIfMissing = false
)
public class DataSourceAutoConfiguration { }

Checks the value of a property. matchIfMissing = true means "activate if the property is missing entirely."

@ConditionalOnResource

@ConditionalOnResource(resources = "classpath:my-config.properties")

@ConditionalOnWebApplication / @ConditionalOnNotWebApplication

@ConditionalOnWebApplication(type = Type.SERVLET)

@ConditionalOnExpression

@ConditionalOnExpression("${my.feature.enabled:false} and '${my.mode}' == 'advanced'")

Uses SpEL. Not recommended for auto-configurations — it's slow and plays poorly with AOT.

5.5.3. ConfigurationPhase — a Subtlety

A @Conditional can be evaluated on two phases:

public enum ConfigurationPhase {
    PARSE_CONFIGURATION,  // while parsing @Configuration
    REGISTER_BEAN         // while registering beans
}

@ConditionalOnBean and @ConditionalOnMissingBean use REGISTER_BEAN, because they need to know which beans are already registered. The rest (@ConditionalOnClass, @ConditionalOnProperty) use PARSE_CONFIGURATION.

5.6. Auto-configuration Ordering

When you have 150+ auto-configurations, the order in which they're applied is critical. For example, DataSourceAutoConfiguration must come before JpaRepositoriesAutoConfiguration.

5.6.1. @AutoConfigureBefore / @AutoConfigureAfter

@AutoConfiguration(after = DataSourceAutoConfiguration.class)
public class JpaRepositoriesAutoConfiguration { }

Or via the standalone annotations:

@AutoConfiguration
@AutoConfigureAfter(DataSourceAutoConfiguration.class)
public class JpaRepositoriesAutoConfiguration { }

These annotations don't guarantee an absolute order — they only define a relative one. Spring Boot sorts the dependency graph via AutoConfigurationSorter.

5.6.2. @AutoConfigureOrder

@AutoConfiguration
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)
public class MyEarlyAutoConfiguration { }

The semantics are the same as @Order, but for auto-configurations. It's used when auto-configurations know nothing about each other and can't reference one another via before/after.

5.6.3. AutoConfigurationSorter — how the sorting works

class AutoConfigurationSorter {
    void sort(List<String> classNames) {
        // 1. Reads each class's metadata (ASM)
        // 2. Builds the graph: A before B, A after C
        // 3. Topological sort
        // 4. Resolves conflicts via @AutoConfigureOrder
    }
}

Priority: @AutoConfigureBefore / @AutoConfigureAfter > @AutoConfigureOrder.

5.7. Creating Your Own Auto-configuration

5.7.1. The auto-configuration class

@AutoConfiguration
@ConditionalOnClass(MyService.class)
@EnableConfigurationProperties(MyServiceProperties.class)
public class MyServiceAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MyService myService(MyServiceProperties properties) {
        return new MyService(properties.getEndpoint(), properties.getTimeout());
    }
}

5.7.2. Properties

@ConfigurationProperties(prefix = "my.service")
public class MyServiceProperties {
    private String endpoint = "http://localhost:8080";
    private Duration timeout = Duration.ofSeconds(5);
    // getters/setters
}

5.7.3. Registration in .imports

The file:

src/main/resources/META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

The content:

com.example.autoconfigure.MyServiceAutoConfiguration

5.7.4. The starter

So that users can add a single dependency, you ship a starter — an empty JAR that pulls in:

<dependency>
    <groupId>com.example</groupId>
    <artifactId>my-service-spring-boot-starter</artifactId>
</dependency>

Inside the starter's pom.xml:

<dependencies>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>my-service</artifactId>
    </dependency>
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>my-service-spring-boot-autoconfigure</artifactId>
    </dependency>
</dependencies>

Naming convention: xxx-spring-boot-starter (for users) and xxx-spring-boot-autoconfigure (for the auto-configuration code).

5.8. Spring Boot 3 vs Spring Boot 4: Key Differences

5.8.1. Modularization of spring-boot-autoconfigure

This is the biggest change in Boot 4.

Aspect	Spring Boot 3.x	Spring Boot 4.x
Artifact	A single monolithic `spring-boot-autoconfigure` (2 MiB in 3.5)	47 modular JARs, one per technology
Size	Everything in one place	Only the modules you need end up on the classpath
Web auto-configurations	In `spring-boot-autoconfigure`	In `spring-boot-webmvc` / `spring-boot-webflux`
JPA auto-configurations	In `spring-boot-autoconfigure`	In `spring-boot-data-jpa`
IDE hints	All classes of all technologies	Only the ones actually in use

The official announcement explains the motivation: "Instead of a single, monolithic spring-boot-autoconfigure jar, we are now splitting functionality into small and more focused modules. This change is motivated by maintainability, clarity, and a leaner runtime footprint."

5.8.2. What Hasn't Changed

@EnableAutoConfiguration — works the same way.
AutoConfigurationImportSelector — the same mechanism.
.imports files — the same format.
@Conditional* — the same annotations.
@AutoConfigureBefore / @AutoConfigureAfter — the same semantics.

5.8.3. BeanRegistrar — the new alternative

In Spring Framework 7 / Boot 4, BeanRegistrar arrived — programmatic bean registration without @Bean methods:

public class MyBeanRegistrar implements BeanRegistrar {
    @Override
    public void register(BeanRegistry registry, Environment env) {
        if (env.acceptsProfiles(Profiles.of("dev"))) {
            registry.registerBean("myService", MyService.class, 
                spec -> spec.supplier(ctx -> new MyService("dev")));
        }
    }
}

It's registered via @Import(MyBeanRegistrar.class). This is closer to the AOT approach: beans are registered programmatically rather than via reflection.

5.8.4. Starters

Boot 3	Boot 4
`spring-boot-starter-web`	`spring-boot-starter-webmvc`
`spring-boot-starter-webflux`	`spring-boot-starter-webflux` (unchanged)
`spring-boot-starter-data-jpa`	`spring-boot-starter-data-jpa` (unchanged)

5.9. Diagram: the Full Path of Auto-configuration

@SpringBootApplication
  └─ @EnableAutoConfiguration
        └─ @Import(AutoConfigurationImportSelector.class)
              │
              └─ refresh() → invokeBeanFactoryPostProcessors()
                    └─ ConfigurationClassPostProcessor
                          └─ ConfigurationClassParser
                                └─ DeferredImportSelectorGroupingHandler
                                      └─ AutoConfigurationImportSelector.selectImports()
                                            │
                                            ├─ 1. isEnabled()?
                                            ├─ 2. getAttributes() → exclude/excludeName
                                            ├─ 3. getCandidateConfigurations()
                                            │     └─ ImportCandidates.load()
                                            │           └─ META-INF/spring/...AutoConfiguration.imports
                                            │                 (all JARs)
                                            ├─ 4. removeDuplicates()
                                            ├─ 5. getExclusions() → removeAll()
                                            ├─ 6. ConfigurationClassFilter.filter()
                                            │     ├─ OnClassCondition
                                            │     ├─ OnBeanCondition
                                            │     └─ OnWebApplicationCondition
                                            └─ 7. fireAutoConfigurationImportEvents()
                                                  │
                                                  ▼
                                            A list of class names
                                                  │
                                                  ▼
                                            ConfigurationClassParser processes
                                            each class as a @Configuration
                                                  │
                                                  ▼
                                            @Bean methods → BeanDefinitions
                                            @Conditional* → final filtering

5.10. Key Takeaways

@EnableAutoConfiguration → AutoConfigurationImportSelector is the single entry point. The selector is a DeferredImportSelector, so auto-configurations are processed after user-defined beans.
.imports files (Boot 3+) replaced spring.factories for auto-configurations. The path: META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports.
@AutoConfiguration is the new annotation for auto-configuration classes: proxyBeanMethods = false, carries @AutoConfigureBefore/After.
@Conditional* annotations work in two passes: coarse-grained filtering via AutoConfigurationImportFilter (by classes/beans), then fine-grained via ConfigurationClassParser.
@ConditionalOnMissingBean is the "back-off" mechanism: if you've declared your own bean, the auto-configuration backs off.
Ordering is defined by @AutoConfigureBefore / @AutoConfigureAfter (relative) and @AutoConfigureOrder (absolute). Sorting is done by AutoConfigurationSorter.
Boot 4 — modularization: 47 modules instead of a single spring-boot-autoconfigure. The auto-configuration mechanism itself hasn't changed, only the packaging.
Your own auto-configuration = @AutoConfiguration + @ConditionalOnClass + @ConditionalOnMissingBean + an .imports file + a starter.

DEV Community: Silver_dev

The finale of the Vector Database Showroom series.

The cost-of-ownership table

The one-day test drive

Before you start

(2–3 hours)

(2 hours) — the scorecard

The method doesn't expire

Vector database showroom. Part 6 Milvus — The High-Speed Freight Train

🚄 Milvus — The High-Speed Freight Train

Where it shines:

Where it stalls:

What breaks if you skip the manual:

Vector database showroom. Part 5 Pinecone — The Car by Subscription

🚕 Pinecone — The Car by Subscription

Where it shines:

Where it stalls:

What breaks if you skip the manual:

Vector database showroom. Part 4 Weaviate — The Crossover That Ships Fully Loaded

🚐 Weaviate — The Crossover That Ships Fully Loaded

Where it shines:

Where it stalls:

What breaks if you skip the manual:

Vector database showroom. Part 3 Qdrant — The Hot Hatchback That Carries More Than It Looks

🏎️ Qdrant — The Hot Hatchback That Carries More Than It Looks

Where it shines:

Where it stalls:

What breaks if you skip the manual:

Vector database showroom. Part 2: Chroma — The E-Scooter That Starts in 90 Second

🛴 Chroma — The E-Scooter That Starts in 90 Seconds

Where it shines:

Where it stalls:

What breaks if you skip the manual:

Vector database showroom. Part 1 pgvector — The Station Wagon Already in Your Garage.

🚙 pgvector — The Station Wagon Already in Your Garage

Where it shines:

Where it stalls:

What breaks if you skip the manual:

Spring Boot Under the Hood. Part 9: Actuator, DevTools and the Rest of the Toolbox

9.1. Actuator — Production-Ready Monitoring

9.1.1. Adding it

9.1.2. Built-in Endpoints

9.1.3. Your Own @Endpoint

9.1.4. HealthIndicators

9.1.5. Micrometer

9.1.6. Boot 4: Actuator Changes

9.2. Logging

9.2.1. The Defaults

9.2.2. Configuration

9.2.3. Levels via Properties

9.2.4. Structured Logging (Boot 3.4+)

9.2.5. Boot 4: Changes

9.3. DevTools — Speeding Up Development

9.3.1. Automatic Restart

9.3.2. LiveReload

9.3.3. include/exclude Configuration

9.3.4. Global Settings

9.4. Testing

9.4.1. @SpringBootTest — the Full Context

9.4.2. Slice Tests — Narrow Contexts

9.4.3. @MockitoBean — Replacing @MockBean in Boot 4

9.4.4. ApplicationContextRunner — Testing Auto-configurations

9.5. Build and Packaging

9.5.1. spring-boot-maven-plugin

9.5.2. Layered JAR

9.5.3. JarLauncher

9.5.4. Buildpacks

9.5.5. Boot 4: Changes

9.6. AOT and GraalVM Native Image (an Overview)

9.6.1. What Is AOT

9.6.2. RuntimeHintsRegistrar

9.6.3. @RegisterReflectionForBinding — a Shortcut

9.6.4. Building a Native Image

9.6.5. Boot 4: AOT by Default

9.7. Summary Table: Boot 3 vs Boot 4

9.8. Key Takeaways

Spring Boot Under the Hood. Part 8: Graceful Exit — How Spring Boot Starts and Stops

8.1. ApplicationRunner and CommandLineRunner — the Entry Point into the "Ready" Application

8.2. The Order in Which Runners Are Invoked

8.3. The Rule: Runners Instead of @PostConstruct

9.1.3. Your Own `@Endpoint`

Step 1: `createBean()` — the entry point

Step 2: `resolveBeforeInstantiation()` — the early proxy

Step 4: `createBeanInstance()` — choosing the constructor

Step 5: `populateBean()` — injecting dependencies

Step 6: `initializeBean()` — initialization