Spring 自定義 XML Schema 擴充實戰（一）：命名空間與註解驅動 WebService 發布

目標

擴充 Spring XML 配置，支援自定義命名空間 std，讓開發者能寫：

<std:annotation-endpoint package="com.example.ws"/>

自動掃描 @Endpoint 註解並發布 WebService（基於 CXF）。

專案結構

src/main/resources/
├── META-INF/
│   ├── spring.schemas
│   ├── spring.handlers
│   └── schema/
│       └── stdws-1.0.xsd
└── com/codestd/spring/cxf/annotation/
    ├── Endpoint.java
    └── config/
        ├── StdNamespaceHandler.java
        └── AnnotationEndpointBeanDefinitionParser.java

1. 定義 XSD Schema

src/main/resources/META-INF/schema/stdws-1.0.xsd

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns="https://www.codestd.com/schema/std/ws"
    xmlns:xsd="https://www.w3.org/2001/XMLSchema"
    xmlns:beans="https://www.springframework.org/schema/beans"
    targetNamespace="https://www.codestd.com/schema/std/ws"
    elementFormDefault="qualified" attributeFormDefault="unqualified">

    <xsd:import namespace="https://www.springframework.org/schema/beans"/>

    <xsd:element name="annotation-endpoint">
        <xsd:complexType>
            <xsd:complexContent>
                <xsd:extension base="beans:identifiedType">
                    <xsd:attribute name="name" type="xsd:string" use="optional"/>
                    <xsd:attribute name="package" type="xsd:string" use="optional"/>
                </xsd:extension>
            </xsd:complexContent>
        </xsd:complexType>
    </xsd:element>
</xsd:schema>

2. 註冊 Schema 與 Handler 映射

spring.schemas（關鍵：讓 Spring 解析 XML 時離線載入 XSD，避免網路請求）

http\://www.codestd.com/schema/std/ws/stdws-1.0.xsd=META-INF/schema/stdws-1.0.xsd

spring.handlers

http\://www.codestd.com/schema/std/ws=com.codestd.spring.cxf.config.StdNamespaceHandler

3. 實作 NamespaceHandler

public class StdNamespaceHandler extends NamespaceHandlerSupport {
    @Override
    public void init() {
        registerBeanDefinitionParser("annotation-endpoint", new AnnotationEndpointBeanDefinitionParser());
    }
}

4. 實作 BeanDefinitionParser（核心邏輯）

public class AnnotationEndpointBeanDefinitionParser implements BeanDefinitionParser {
    @Override
    public BeanDefinition parse(Element element, ParserContext parserContext) {
        String packageToScan = element.getAttribute("package");
        String beanName = element.getAttribute("name");

        // 1. 註冊 ComponentScanBeanDefinitionParser 掃描 @Endpoint
        RootBeanDefinition scanDef = new RootBeanDefinition(ClassPathBeanDefinitionScanner.class);
        scanDef.getConstructorArgumentValues().addGenericArgumentValue(packageToScan);
        // 設定 includeFilters 只掃描 @Endpoint
        // ... 省略細節

        // 2. 註冊 CXF Endpoint 發布邏輯（簡化示意）
        RootBeanDefinition endpointDef = new RootBeanDefinition(EndpointPublisher.class);
        endpointDef.getPropertyValues().add("packageToScan", packageToScan);

        parserContext.getRegistry().registerBeanDefinition(beanName, endpointDef);
        return null;
    }
}

5. 自定義註解 @Endpoint

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Endpoint {
    String id();       // Spring Bean ID
    String address();  // 發布位址，如 /services/MyService
}

6. 使用範例

applicationContext.xml

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="https://www.springframework.org/schema/beans"
    xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
    xmlns:std="https://www.codestd.com/schema/std/ws"
    xsi:schemaLocation="
        https://www.springframework.org/schema/beans https://www.springframework.org/schema/beans/spring-beans-4.0.xsd
        https://www.codestd.com/schema/std/ws https://www.codestd.com/schema/std/ws/stdws-1.0.xsd">

    <std:annotation-endpoint package="com.codestd.spring.cxf.ws"/>

</beans>

IDE 設定提示（Eclipse/IntelliJ）

1. Preferences → XML → XML Catalog → Add
2. Location: 選擇專案內 stdws-1.0.xsd
3. Key Type: Namespace Name
4. Key: https://www.codestd.com/schema/std/ws/stdws-1.0.xsd

即可享有 XML 內容提示與驗證。

關鍵技術點總結

結語

Spring 自定義 Schema 擴充讓 XML 配置具備領域語言（DSL）表達力，封裝複雜的 Bean 組裝邏輯。本文示範的「註解掃描 + CXF 發布」僅是冰山一角；實務中可擴充至資料源配置、快取註解、安全規則等任何重複性基礎設施配置，顯著提升團隊開發效率與配置可讀性。