订单服务启动时读到了仓库名称,打印装箱单时还需要模板和徽标,只有属性配置不够。Spring Cloud 2026.0.0-RC2 的 ConfigResourceClient 可以把 Config Server 上的纯文本、二进制文件读成 Resource,复用配置导入的连接设置。本例还把文件单独切到另一个 label:模板和图片变了,启动时导入的仓库属性没有跟着变。

新的是客户端,不是文件端点

11 月 5 日的 RC2 公告把这项变化列在 Config 下,对应 #3355。Config Server 原本就能提供文件;这次补上的是客户端的 Resource 抽象,不是首次支持拉取 Environment 或属性。

下面用 Spring Boot 4.2.0-RC2、Cloud BOM 2026.0.0-RC2,实际解析到 Config Server、Client 和 starter 5.1.0-RC2,Spring Framework 7.1.0-RC2。服务端使用 native 文件后端,只监听本机;这不是 Git 分支或生产代理验证。

客户端已有的 Config Client OAuth2 变化处理的是连接认证。本例不接认证服务,关注同一个 Config Server 连接如何同时提供属性和业务文件。

一份属性、一份模板、一张 PNG

配置应用名是 orders,profile 是 prod。业务进程名故意设成 order-runtime,用来区分运行应用名与 ConfigClientProperties 中真正参与查找的 name。

native 后端把 main 和 release/2026 映射到两个目录。前者仓库为 Shanghai-A、蓝色 PNG,后者为 Shanghai-B、红色 PNG。两份模板原文相同:

PACKING SLIP
Warehouse=${warehouse.name}
Order={{orderId}}

${warehouse.name} 由 Config Server 的纯文本端点按所选 Environment 替换;{{orderId}} 是留给订单业务的标记,本例没有渲染订单号。PNG 则走二进制读取,不做模板替换。

首次运行,没有给客户端配置 label。客户端输出如下,模板是处理后的文本,图片则逐字节与服务端原文件比对成功:

PROPERTY warehouse=Shanghai-A max-items=12
TEXT PACKING SLIP\nWarehouse=Shanghai-A\nOrder={{orderId}}\n
BINARY filename=logo.png bytes=72 sha256=54a9b6d89c1db209418715a40e125cf0289b475088cc0161d5db170b92d9277e magic=89504e470d0a1a0a
REOPEN same=true

PNG 的前八字节是实际读出的签名,SHA-256 来自下载内容,不是预写常量。这里 REOPEN 是再次读取同一个已返回的 Resource,不是再次下载,也不能据此声称有跨调用缓存。

服务端过滤器记录的真实请求为:

HTTP method=GET target=/orders/prod accept=application/vnd.spring-cloud.config-server.v2+json status=200
HTTP method=GET target=/orders/prod/templates/packing-slip.txt?useDefaultLabel accept=*/* status=200
HTTP method=GET target=/orders/prod/images/logo.png?useDefaultLabel accept=application/octet-stream status=200
HTTP method=GET target=/orders/prod/templates/missing.txt?useDefaultLabel accept=*/* status=404

第一条是启动时导入属性,后面才是业务代码读文件。没有 label 的文件请求确实带 ?useDefaultLabel;它让服务端选择默认 label,不是在 URL 中硬编码 main。缺失模板返回 404,示例捕获后输出 MISSING status=404,进程正常退出。

文件选版,不会重绑已经导入的属性

API 有两个入口接口:PlainTextConfigClient 和 BinaryResourceConfigClient。ConfigResourceClient 同时继承它们;单参数方法只给文件路径,三参数方法依次指定 profile、label、path。RC2 默认实现 DefaultConfigResourceClient 基于 RestClient。

不传覆盖值时,name、profile、label 来自 ConfigClientProperties。实验结果如下:

调用方式 启动属性 warehouse 模板 Warehouse 图片字节数
不配置 label,调用单参数方法 Shanghai-A Shanghai-A 72
配置 label 为 release/2026,调用单参数方法 Shanghai-B Shanghai-B 73
启动时不配 label,读文件时显式传 release/2026 Shanghai-A Shanghai-B 73

第三组的实际输出:

PROPERTY warehouse=Shanghai-A max-items=12
TEXT PACKING SLIP\nWarehouse=Shanghai-B\nOrder={{orderId}}\n
BINARY filename=logo.png bytes=73 sha256=2aad03f834dbe2396594efe137e941e356709cc1bfa44ea242e00e913dc9877d magic=89504e470d0a1a0a

该组只给文件方法传了 prod、release/2026。属性请求仍没有 label,文件请求中的斜杠则按 Config Server 约定写成 (_):

HTTP method=GET target=/orders/prod accept=application/vnd.spring-cloud.config-server.v2+json status=200
HTTP method=GET target=/orders/prod/release(_)2026/templates/packing-slip.txt accept=*/* status=200
HTTP method=GET target=/orders/prod/release(_)2026/images/logo.png accept=application/octet-stream status=200
HTTP method=GET target=/orders/prod/templates/missing.txt?useDefaultLabel accept=*/* status=404

二进制调用还明确发送 Accept: application/octet-stream。本例的 release/2026 是 native 后端的目录 label,不是实际 Git 分支。

这意味着,模板灰度可以只改本次文件选择,不必替换整个 Environment;反过来,若模板内容必须与启动属性属于同一版本,就应统一 label,不能把三参数方法当成属性刷新操作。

import 与大小上限是两条不同边界

正常自动装配需要 spring.config.import=configserver:...。RC2 的自动配置依赖导入流程创建的 ConfigServerRestClientHolder,并复用其连接设置;只加 starter 不等于有可用的 Resource 客户端。实验使用真正不含 import 的外部配置文件,默认启动检查直接失败,退出码为 1:

No spring.config.import property has been defined

为了单独观察 Bean 条件,另一次仅在该无 import 配置上关闭 spring.cloud.config.import-check.enabled。应用可以启动,但输出为:

PROPERTY warehouse=<absent> max-items=<absent>
RESOURCE_CLIENT present=false

这两组都没有请求 Config Server。关闭检查不是补回 Resource 客户端的方法;正常用法仍是保留 import。手工创建客户端或替换相关 Bean 不属于这里的自动装配测试。

文件会完整缓存在内存里。RC2 JAR 的配置元数据给 spring.cloud.config.resource-client.max-size 的默认值为 1MB,设为 0 会取消上限,不是开启流式下载。将上限设为 32B 后,同一张 72 字节 PNG 在客户端读取时被拒绝:

LIMIT The file [images/logo.png] exceeds the maximum size of 32 bytes; raise spring.cloud.config.resource-client.max-size to read it

对应服务端请求仍是 200。异常发生在业务读取阶段,示例捕获后退出码为 0,不是启动失败,也不是服务端返回了超限 HTTP 状态。

可复制的最小工程

需要 JDK 21、Maven 3.9、Python 3、curl 和 Bash。在空目录中按以下相对路径保存文件。服务端只开放 127.0.0.1:18888;该端口已被占用时,脚本会退出,不会停止占用者。

mkdir -p server/src/main/java/example client/src/main/java/example client/src/main/resources

server/pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>4.2.0-RC2</version><relativePath/></parent>
 <groupId>example</groupId><artifactId>resource-server</artifactId><version>1.0.0</version>
 <properties><java.version>21</java.version><spring-cloud.version>2026.0.0-RC2</spring-cloud.version></properties>
 <dependencyManagement><dependencies><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-dependencies</artifactId><version>${spring-cloud.version}</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement>
 <dependencies><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-config-server</artifactId></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-webmvc</artifactId></dependency></dependencies>
 <build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>
</project>

client/pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>4.2.0-RC2</version><relativePath/></parent>
 <groupId>example</groupId><artifactId>resource-client</artifactId><version>1.0.0</version>
 <properties><java.version>21</java.version><spring-cloud.version>2026.0.0-RC2</spring-cloud.version></properties>
 <dependencyManagement><dependencies><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-dependencies</artifactId><version>${spring-cloud.version}</version><type>pom</type><scope>import</scope></dependency></dependencies></dependencyManagement>
 <dependencies><dependency><groupId>org.springframework.cloud</groupId><artifactId>spring-cloud-starter-config</artifactId></dependency></dependencies>
 <build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>
</project>

server/src/main/java/example/ConfigServerApp.java

package example;

import java.io.IOException;
import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.config.server.EnableConfigServer;
import org.springframework.context.annotation.Bean;
import org.springframework.web.filter.OncePerRequestFilter;

@SpringBootApplication
@EnableConfigServer
public class ConfigServerApp {
    public static void main(String[] args) { SpringApplication.run(ConfigServerApp.class, args); }
    @Bean
    OncePerRequestFilter requests() {
        return new OncePerRequestFilter() {
            @Override
            protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
                    FilterChain chain) throws ServletException, IOException {
                try { chain.doFilter(request, response); }
                finally {
                    String target = request.getRequestURI();
                    if (request.getQueryString() != null) target += "?" + request.getQueryString();
                    System.out.println("HTTP method=" + request.getMethod() + " target=" + target
                            + " accept=" + request.getHeader("Accept") + " status=" + response.getStatus());
                }
            }
        };
    }
}

client/src/main/resources/application.properties

spring.main.web-application-type=none
spring.main.banner-mode=off
spring.application.name=order-runtime
spring.cloud.config.name=orders
spring.cloud.config.profile=prod
spring.config.import=configserver:http://127.0.0.1:18888

client/src/main/java/example/OrderApp.java

package example;

import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.MessageDigest;
import java.util.Arrays;
import java.util.HexFormat;
import org.springframework.beans.factory.ObjectProvider;
import org.springframework.boot.ApplicationRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.SpringBootVersion;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.config.client.ConfigResourceClient;
import org.springframework.cloud.config.client.PlainTextConfigClient;
import org.springframework.cloud.config.client.BinaryResourceConfigClient;
import org.springframework.context.annotation.Bean;
import org.springframework.core.env.Environment;
import org.springframework.core.io.Resource;
import org.springframework.web.client.HttpClientErrorException;

@SpringBootApplication
public class OrderApp {
    public static void main(String[] args) {
        try (var context = SpringApplication.run(OrderApp.class, args)) { }
    }
    @Bean
    ApplicationRunner inspect(ObjectProvider<ConfigResourceClient> provider, Environment environment) {
        return args -> {
            ConfigResourceClient client = provider.getIfAvailable();
            System.out.println("RUNTIME boot=" + SpringBootVersion.getVersion());
            System.out.println("PROPERTY warehouse=" + environment.getProperty("warehouse.name", "<absent>")
                    + " max-items=" + environment.getProperty("packing.max-items", "<absent>"));
            System.out.println("RESOURCE_CLIENT present=" + (client != null));
            if (client == null) return;
            System.out.println("IMPLEMENTATION " + client.getClass().getName());
            if (environment.getProperty("demo.limit", Boolean.class, false)) {
                try { client.getBinaryResource("images/logo.png"); throw new AssertionError("Expected size rejection"); }
                catch (IllegalStateException ex) { System.out.println("LIMIT " + ex.getMessage()); }
                return;
            }
            String label = environment.getProperty("demo.explicit-label");
            PlainTextConfigClient textClient = client;
            BinaryResourceConfigClient binaryClient = client;
            Resource text = label == null ? textClient.getPlainTextResource("templates/packing-slip.txt")
                    : textClient.getPlainTextResource("prod", label, "templates/packing-slip.txt");
            Resource logo = label == null ? binaryClient.getBinaryResource("images/logo.png")
                    : binaryClient.getBinaryResource("prod", label, "images/logo.png");
            byte[] textBytes = text.getContentAsByteArray();
            byte[] png = logo.getContentAsByteArray();
            Path out = Path.of(environment.getProperty("demo.out", "received"));
            Files.createDirectories(out);
            Files.write(out.resolve("packing-slip.txt"), textBytes);
            Files.write(out.resolve("logo.png"), png);
            System.out.println("TEXT " + new String(textBytes, StandardCharsets.UTF_8).replace("\n", "\\n"));
            System.out.println("BINARY filename=" + logo.getFilename() + " bytes=" + png.length
                    + " sha256=" + HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(png))
                    + " magic=" + HexFormat.of().formatHex(Arrays.copyOf(png, 8)));
            System.out.println("REOPEN same=" + Arrays.equals(png, logo.getContentAsByteArray()));
            try { client.getPlainTextResource("templates/missing.txt"); throw new AssertionError("Expected 404"); }
            catch (HttpClientErrorException.NotFound ex) { System.out.println("MISSING status=" + ex.getStatusCode().value()); }
        };
    }
}

fixtures.py

from pathlib import Path
import struct, zlib

def png(rgb):
    def chunk(kind, data):
        return struct.pack('!I', len(data)) + kind + data + struct.pack('!I', zlib.crc32(kind + data))
    return (b'\x89PNG\r\n\x1a\n'
        + chunk(b'IHDR', struct.pack('!2I5B', 2, 2, 8, 2, 0, 0, 0))
        + chunk(b'IDAT', zlib.compress((b'\0' + bytes(rgb) * 2) * 2)) + chunk(b'IEND', b''))

for label, warehouse, rgb in [('main', 'Shanghai-A', [0, 70, 160]),
                               ('release/2026', 'Shanghai-B', [180, 20, 40])]:
    root = Path('config-repo/orders') / label
    (root / 'templates').mkdir(parents=True, exist_ok=True)
    (root / 'images').mkdir(exist_ok=True)
    (root / 'orders-prod.properties').write_text(
        'warehouse.name=' + warehouse + '\npacking.max-items=12\n', encoding='utf-8')
    (root / 'templates/packing-slip.txt').write_text(
        'PACKING SLIP\nWarehouse=${warehouse.name}\nOrder={{orderId}}\n', encoding='utf-8')
    (root / 'images/logo.png').write_bytes(png(rgb))

run.sh

#!/usr/bin/env bash
set -euo pipefail
ROOT="$PWD"
LOG="run-logs-$(date +%Y%m%d-%H%M%S)"
mkdir "$LOG"
python3 - <<'PY'
import socket
with socket.socket() as s:
    s.bind(('127.0.0.1', 18888))
PY
java -XX:ActiveProcessorCount=2 -Xmx384m -jar server/target/resource-server-1.0.0.jar \
  --server.address=127.0.0.1 --server.port=18888 --spring.profiles.active=native \
  "--spring.cloud.config.server.native.search-locations=file:$ROOT/config-repo/{application}/{label}/" \
  --spring.cloud.config.server.native.default-label=main \
  --spring.cloud.config.server.native.add-label-locations=false > "$LOG/server.log" 2>&1 &
SERVER_PID=$!
cleanup() { kill "$SERVER_PID" 2>/dev/null || true; wait "$SERVER_PID" 2>/dev/null || true; }
trap cleanup EXIT
READY=false
for i in {1..120}; do
  kill -0 "$SERVER_PID"
  if curl -fsS http://127.0.0.1:18888/orders/prod > "$LOG/readiness.json"; then
    READY=true; break
  fi
  sleep 0.25
done
[[ "$READY" == true ]]
for case in default configured-label explicit-label no-import no-import-no-check small-limit; do
  mkdir "$LOG/$case"
  python3 - "$case" "$LOG/$case/application.properties" <<'PY'
from pathlib import Path
import sys
text = Path('client/src/main/resources/application.properties').read_text()
if sys.argv[1].startswith('no-import'):
    text = '\n'.join(s for s in text.splitlines() if not s.startswith('spring.config.import=')) + '\n'
Path(sys.argv[2]).write_text(text)
PY
  EXTRA=()
  case "$case" in
    configured-label) EXTRA+=(--spring.cloud.config.label=release/2026);;
    explicit-label) EXTRA+=(--demo.explicit-label=release/2026);;
    no-import-no-check) EXTRA+=(--spring.cloud.config.import-check.enabled=false);;
    small-limit) EXTRA+=(--spring.cloud.config.resource-client.max-size=32B --demo.limit=true);;
  esac
  CODE=0
  java -XX:ActiveProcessorCount=2 -Xmx256m -jar client/target/resource-client-1.0.0.jar \
    "--spring.config.location=file:$ROOT/$LOG/$case/application.properties" \
    "--demo.out=$ROOT/$LOG/$case/received" "${EXTRA[@]}" > "$LOG/$case/client.log" 2>&1 || CODE=$?
  printf '%s\n' "$CODE" > "$LOG/$case/exit-code.txt"
done
python3 - "$LOG" <<'PY'
from pathlib import Path
import sys
root = Path(sys.argv[1])
for name in ['default', 'configured-label', 'explicit-label']:
    received = root / name / 'received'
    label = 'main' if name == 'default' else 'release/2026'
    original = Path('config-repo/orders') / label
    assert (received / 'logo.png').read_bytes() == (original / 'images/logo.png').read_bytes()
    warehouse = 'Shanghai-A' if name == 'default' else 'Shanghai-B'
    assert (received / 'packing-slip.txt').read_text() == (
        'PACKING SLIP\nWarehouse=' + warehouse + '\nOrder={{orderId}}\n')
    assert (root / name / 'exit-code.txt').read_text().strip() == '0'
assert (root / 'no-import/exit-code.txt').read_text().strip() == '1'
assert 'Add a spring.config.import=configserver:' in (root / 'no-import/client.log').read_text()
assert 'RESOURCE_CLIENT present=false' in (root / 'no-import-no-check/client.log').read_text()
assert 'exceeds the maximum size of 32 bytes' in (root / 'small-limit/client.log').read_text()
for name in ['no-import-no-check', 'small-limit']:
    assert (root / name / 'exit-code.txt').read_text().strip() == '0'
print('PASS: template, PNG bytes, labels, import guard and size limit')
PY

依次生成文件、打包、运行:

python3 fixtures.py
mvn -q -f server/pom.xml package
mvn -q -f client/pom.xml package
bash run.sh

脚本实际启动 Config Server,顺序执行表中的三组业务读取,再检查无 import、关闭检查后的 Bean 缺失及大小上限。它把每次客户端输出、退出码、下载内容和服务端原始请求保存到新建的 run-logs-* 目录;结束时只停止自己启动的服务。字节和文本比较全部通过后输出:

PASS: template, PNG bytes, labels, import guard and size limit

本例没有验证 Git 后端、认证、TLS、集群故障切换或动态属性刷新。它验证的是同一台真实 Config Server 上,启动配置进入 Environment,业务模板与徽标按需进入 Resource,而文件级 label 覆盖不会反向改动已经导入的属性。

相关规则可对照 Config Client 5.1 文档、纯文本文件端点、二进制文件端点 5.1 文档及 5.1.0-RC2 客户端源码。5.1 文档分支可能继续更新,本文的 API、请求与大小上限另以 RC2 标签源码、JAR 元数据和上述运行结果交叉核对。

— 感谢阅读 —
广告

一起交流

分享你的思考,让讨论更进一步。