Apollo 入门教程：本地快速启动与 Spring Boot 客户端接入

新手一屏速览

本地用 Apollo Quick Start 容器快速体验
Spring Boot 集成 apollo-client，从配置中心读取 key，未连通时回退默认值
提供完整可复制文件：docker 命令、pom.xml、源码、测试与访问命令

1. 启动 Apollo Quick Start（可直接复制）

docker run -d --name apollo-quickstart -p 8070:8070 -p 8080:8080 ctripcorp/apollo-quick-start

访问 Portal：浏览器打开 http://localhost:8070 （默认用户/密码：apollo/admin）。

2. Spring Boot 客户端接入

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 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>apollo-demo</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <packaging>jar</packaging>
  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.5</version>
  </parent>
  <properties>
    <java.version>21</java.version>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
      <groupId>com.ctrip.framework.apollo</groupId>
      <artifactId>apollo-client</artifactId>
      <version>2.2.0</version>
    </dependency>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
      </plugin>
    </plugins>
  </build>
</project>

application.properties（客户端基础配置）：

server.port=8082
# Apollo Meta Server（dev 环境），Quick Start 缺省内置 http://localhost:8080
apollo.meta=http://localhost:8080
# 当前 AppId，需要在 Portal 上创建
app.id=apollo-demo

DemoApplication.java：

package com.example.apollodemo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * 应用启动入口。
 */
@SpringBootApplication
public class DemoApplication {
  /**
   * 启动应用
   * @param args 命令行参数
   */
  public static void main(String[] args) {
    SpringApplication.run(DemoApplication.class, args);
  }
}

ApiResponse.java：

package com.example.apollodemo.web;

/**
 * 统一响应对象。
 * @param <T> 数据类型
 */
public class ApiResponse<T> {
  private boolean success;
  private T data;
  private String error;
  public static <T> ApiResponse<T> ok(T data){ ApiResponse<T> r=new ApiResponse<>(); r.success=true; r.data=data; return r; }
  public static <T> ApiResponse<T> fail(String msg){ ApiResponse<T> r=new ApiResponse<>(); r.success=false; r.error=msg; return r; }
  public boolean isSuccess(){ return success; } public T getData(){ return data; } public String getError(){ return error; }
}

HelloController.java（读取 key=app.message，未连通时回退默认值）：

package com.example.apollodemo.web;

import com.ctrip.framework.apollo.Config;
import com.ctrip.framework.apollo.ConfigService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * 示例接口：读取 Apollo 配置。
 */
@RestController
public class HelloController {
  /**
   * GET /api/message
   * @return 来自配置中心的消息（或默认值）
   */
  @GetMapping("/api/message")
  public ApiResponse<String> message(){
    Config cfg = ConfigService.getAppConfig();
    String msg = cfg.getProperty("app.message", "default-from-local");
    return ApiResponse.ok(msg);
  }
}

3. 在 Portal 创建项目与配置

登录 http://localhost:8070 创建 AppId 为 apollo-demo 的项目
进入默认 Namespace application，新增键值：

app.message=hello-from-apollo

发布后访问：

curl http://localhost:8082/api/message

应返回 hello-from-apollo，未连通时返回默认 default-from-local。

4. 单元测试（可直接复制）

最近建一些几十个工作内推群，各大城市都有，群里目前已经收集了很多内推岗位，大厂、中厂、小厂、外包都有。欢迎HR、开发、测试、运维和产品加入。

内推群海报

扫描下方微信，备注：网站+所在城市，即可拉你进工作内推群。

微信二维码

package com.example.apollodemo;

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;

/**
 * 验证默认值回退逻辑（无需依赖 Apollo 运行）。
 */
@SpringBootTest
@AutoConfigureMockMvc
class MessageControllerTest {
  @Autowired
  MockMvc mvc;
  @Test
  void should_return_default_when_apollo_unavailable() throws Exception {
    mvc.perform(get("/api/message"))
        .andExpect(status().isOk())
        .andExpect(jsonPath("$.success").value(true))
        .andExpect(jsonPath("$.data").value("default-from-local"));
  }
}

5. 启动与访问

mvn -q -DskipTests spring-boot:run

访问：

curl http://localhost:8082/api/message

6. 常见问题排查

端口与服务：Quick Start 暴露 8070（Portal）与 8080（Config/Admin），确保未被占用
客户端收不到配置：确认 app.id 与 apollo.meta 正确，且已在 Portal 发布
依赖兼容性：如使用其他 Spring 版本，请对齐 apollo-client 支持范围