很多人第一次接觸 Spring AI，會把它理解成「Spring Boot 版的 OpenAI SDK」。這個理解不能說完全錯，但如果停在這裡，做出來的應用通常很快就會遇到瓶頸：提示詞越寫越亂、外部工具越接越難控、知識檢索和對話記憶糾纏在一起，最後只能維持一個 demo 可以跑、但很難進入正式系統的狀態。

真正有價值的 Spring AI 應用，不是把 LLM 接進來而已，而是把 LLM 放進一個可以驗證、可以治理、可以維運的 Java 系統裡。Spring AI 的價值正是在這裡：它不是只提供 model call，而是提供一個把聊天模型、檢索流程、工具調用、上下文攔截與 Spring Boot 工程能力接起來的應用框架。

這篇文章不打算重複官方文件的功能列表，而是從工程角度回答一個更重要的問題：如果你真的要用 Spring AI 做內部知識助理、客服協作、工作流代理或企業工具入口，應該怎麼設計，才不會三個月後整套系統變成不可維護的 prompt 泥沼？

先看一個比較符合真實場景的架構：

spring-ai-app/
 ├─ api layer
 │   └─ ChatController
 ├─ orchestration layer
 │   ├─ ChatClient
 │   ├─ Advisors
 │   └─ Prompt policies
 ├─ knowledge layer
 │   ├─ VectorStore
 │   ├─ QuestionAnswerAdvisor
 │   └─ RetrievalAugmentationAdvisor
 ├─ tool layer
 │   ├─ Internal business tools
 │   └─ MCP client / MCP server
 ├─ policy layer
 │   ├─ Security
 │   ├─ Auditing
 │   └─ Guardrails
 └─ ops layer
     ├─ Metrics / logs / traces
     ├─ Evaluation
     └─ Release workflow

Software architecture is the foundational blueprint that determines the long-term success of an application. For developers working with Spring Boot, architectural choices have a direct impact on maintainability, scalability, and overall development productivity. A poorly chosen structure can result in a codebase that is hard to test, expensive to modify, and slow to evolve. Among the available patterns, Three-Layer Architecture and Clean Architecture are two of the most frequently used approaches. The former emphasizes simplicity and delivery speed, while the latter focuses on domain-centric design and long-term flexibility. This guide provides a clear, comparative analysis of both architectures, complete with practical examples, to help teams make informed decisions based on their project’s goals and constraints.

Hexagonal Architecture (HA), also known as Ports and Adapters Architecture, is a foundational and influential software design pattern, first introduced by Alistair Cockburn in 2005.

The term “Hexagonal Architecture” comes from a visual convention: the application component is drawn as a hexagon, not to imply it must have six boundaries or ports, but to leave enough space to represent the different interfaces connecting the component to the outside world. As Cockburn stated in his 2005 article:

The hexagon is not a hexagon because the number six is important, but rather to allow the people doing the drawing to have room to insert ports and adapters as they need, not being constrained by a one-dimensional layered drawing.

This insight is crucial—it reminds us to stop focusing on the shape and instead focus on the core concept: defining the application’s API via ports and connecting it to the outside world with interchangeable adapters. This shift from diagram to intent is the first step toward architectural maturity.

Ports & Adapters (Hexagonal Architecture) explicitly defines two layers: the inside (application core) and the outside (everything else), and requires clear definition of ports for interaction.

(Clean Architecture builds on this by further splitting the application core into more granular layers such as Use Cases, Entities, and Domain Services, but is less prescriptive about the “port” metaphor for the outer boundary.)

A Complete Guide to Multi-Environment Configuration in Spring Boot

In real-world development and deployment, a single project often needs to run in multiple environments (e.g., local, dev, staging, production).
Spring Boot provides a powerful mechanism for environment-based configuration, allowing us to automatically load different settings based on runtime environment variables.

This article walks through how to design a clean and maintainable multi-environment configuration structure step by step.

A Multi-module Maven Project is a software architecture pattern that allows developers to split a large project into multiple interconnected sub-modules, all managed by a single parent project.

This parent-child Maven structure aligns well with microservices architecture. For example, a parent project can contain gateway and auth-service sub-modules. After packaging, these two modules can be deployed and maintained separately.

It’s important to note that this parent-child relationship is for build management, not a functional hierarchy. The parent POM centralizes dependency management, but it doesn’t mean gateway necessarily depends on auth-service.

Programmatic Dependencies: If the gateway module needs to use classes from auth-service, you would add a dependency in its pom.xml. However, in a typical microservices setup, gateway and auth-service communicate via HTTP APIs or OAuth tokens, eliminating the need for a direct JAR dependency.

A typical multi-module project structure in Maven looks like this:

workspace/
 ├─ pom.xml           <-- Parent POM, defines dependencyManagement, pluginManagement, versions
 ├─ gateway/          <-- Child module
 │   └─ pom.xml
 └─ auth-service/     <-- Child module
     └─ pom.xml

In a microservices architecture, service health checks and a reliable Linux deployment process are key to operational stability. This article will share how to build a health check interface in Spring Boot, combined with version management, and how to deploy and manage a Spring Boot JAR in a Linux environment to achieve automated execution and monitoring.

This article will explain how to build a health check interface in Spring Boot, manage versions using Maven BuildProperties, and use a Makefile for streamlined operations, automating the process from development to deployment. Finally, it will cover running the JAR on Linux and managing it with Supervisor.

What is MyBatis?

MyBatis is a first-class persistence framework that provides an alternative to traditional Object-Relational Mapping (ORM) solutions like Hibernate or JPA. Often referred to as a “SQL Mapper,” MyBatis distinguishes itself by embracing SQL. Instead of abstracting SQL away, it puts developers in full control, mapping SQL statements to Java methods.

The core philosophy of MyBatis is to decouple SQL from application logic while allowing you to leverage the full power of your database. It achieves this by mapping:

• Result Mapping: The results of a SQL query to Java objects.
• Parameter Mapping: Java objects and parameters to SQL statement placeholders.

This approach makes MyBatis an excellent choice for projects that require precise control over SQL, such as financial systems, high-performance transaction platforms, or applications with complex, performance-sensitive queries.

In a Spring Boot ecosystem, MyBatis can be integrated primarily in two ways:

1. Mapper Interface + XML (Recommended): Offers maximum flexibility for writing and maintaining complex SQL.
2. Mapper Interface + Annotations: Suitable for simple queries and smaller projects.