订单服务启动时读到了仓库名称,打印装箱单时还需要模板和徽标,只有属性配置不够。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 元数据和上述运行结果交叉核对。
一起交流
分享你的思考,让讨论更进一步。