尧图网页设计 
一家新公司从成立到产品上线留给技术团队的窗口期通常很短。业务侧已经验证了需求客户在等接口运营在催后台而后端可能还只有一个原型仓库。这个阶段最容易犯的错误是盲目追求架构复杂度一上来就拆微服务、引入 Kubernetes、设计分布式事务。实际上三个月内要交付的是稳定、可维护、能快速迭代的骨架而不是一个理论上无限扩展的庞然大物。下面这套搭建路径适合刚起步的创业团队参考也适合个人开发者搭自己产品时使用。它围绕一台应用服务器、一个关系数据库、一个缓存服务展开先跑通认证、业务和数据迁移再逐步加入容器化部署、日志监控和故障排查手段。1. 先想清楚快速上线阶段技术架构要抓住哪几条主线1.1 从业务诉求倒推技术选型很多团队在选型时先看技术热度再看团队熟悉度最后才考虑业务阶段这个顺序应该反过来。三个月的交付期里最值钱的不是技术栈新不新而是问题能不能快速定位、新成员能不能快速上手、依赖组件能不能在云服务器上低成本跑起来。选型要从三个问题倒推产品的主要用户是谁预计流量规模多大。早期通常只有几千到几万用户一台 4 核 8G 服务器已经足够承载业务主体。团队最熟悉哪门语言和框架。不建议在起步阶段引入全员都没接触过的语言即使它再适合所谓高并发也会在招聘、培训和排错上付出额外成本。业务是重逻辑还是重数据。如果核心是下单、对账、权限那么关系数据库一定是主存储如果核心是文案、图片、外部 API 转发那么对数据库一致性的要求可以降低但对外部服务稳定性要求会更高。常见技术选型可以做如下对比技术组件典型选型用途早期成本后端框架Spring Boot 或 Node.js/NestJS提供 HTTP API、业务逻辑低关系数据库PostgreSQL 或 MySQL用户、订单、配置等结构化数据低缓存Redis会话、验证码、热点数据低对象存储云厂商 OSS/S3 兼容服务图片、文件、静态资源按量付费部署环境Docker Docker Compose本地与生产一致化低反向代理Nginx域名转发、SSL 终止、静态资源服务低这套选型不是唯一答案但足够稳。它不需要一开始就维护多套环境、多个服务实例也能在业务量上来之后平滑扩展。1.2 先搭单体应用不要一上来就拆微服务微服务解决的是团队扩大、模块独立发布、故障隔离等问题但它也会引入服务发现、配置中心、分布式事务、链路追踪等额外复杂度。对三个月上线目标来说这些复杂度会直接吃掉排期。正确做法是做一个“模块化单体”一个应用工程按业务域拆包。不跨模块直接调用数据库表而是通过 Service 接口。模块间通过普通 Java 方法调用而不是 HTTP 调用。预留独立的对外 API 入口但内部保持单体部署。比如按用户、内容、订单三个域拆包com.example.startup ├── common ├── user ├── content └── order每个业务域内部可以有自己的 controller、service、repository。这样未来某个域确实需要拆分时可以直接把对应包抽成独立服务而不用重写业务逻辑。1.3 明确开发、测试、运维的工作边界早期团队可能没有专职运维开发也兼任测试。此时最怕的是职责不清导致生产环境变成“谁都能动谁都不负责”。建议划分如下开发负责本地环境、代码实现、单元测试、接口自测。测试负责测试环境验证、回归用例、线上冒烟测试。运维负责服务器初始化、部署脚本、日志备份、监控告警。如果没人专职至少指定一个人负责而不是轮流值班。任何生产环境变更都要有记录哪怕是执行一条 SQL也要写明时间、原因、操作人、回滚方式。这个顺序看起来简单但很多事故都源于生产环境变更没有记录。早期哪怕用一张在线表格记录也比完全无序强。2. 环境准备与依赖版本一套能复现的本地开发环境2.1 基础环境清单快速上线阶段环境问题最容易造成“本地能跑服务器跑不了”。要减少这类问题最好把所有基础环境写进项目 README并用脚本或容器固定下来。以 Java 技术栈为例本地环境建议如下组件用途验证命令JDK 17 或 21编译和运行 Spring Bootjava -versionMaven 或 Gradle依赖管理mvn -vDocker运行中间件和部署docker --versionDocker Compose编排本地中间件docker compose versionPostgreSQL 或 MySQL 客户端连接数据库执行 SQLpsql --versionRedis 客户端查看缓存内容redis-cli ping如果你不想本地安装数据库和 Redis最简单的方式是用 Docker 启动中间件。下面是一个本地中间件编排示例services: postgres: image: postgres:16 container_name: startup-postgres environment: POSTGRES_DB: startup POSTGRES_USER: startup POSTGRES_PASSWORD: startup123 ports: - 5432:5432 volumes: - postgres-data:/var/lib/postgresql/data redis: image: redis:7 container_name: startup-redis ports: - 6379:6379 volumes: postgres-data:启动命令docker compose up -d检查结果docker ps如果容器状态是 Up说明数据库和缓存都已启动。这里要注意容器里的数据默认写到 named volume删除容器不会丢数据。如果使用不带 volume 的方式删除容器后数据会丢失。2.2 初始化 Spring Boot 项目使用 Spring Initializr 初始化项目最简单。如果是命令行操作可以用 curl 生成基础工程curl https://start.spring.io/starter.zip \ -d typemaven-project \ -d languagejava \ -d bootVersion3.3.0 \ -d groupIdcom.example \ -d artifactIdstartup \ -d namestartup \ -d packageNamecom.example.startup \ -d dependenciesweb,data-jpa,security,validation,redis,flyway,actuator,postgresql \ -o startup.zip解压后导入 IDE。关键依赖说明spring-boot-starter-web提供 HTTP API。spring-boot-starter-data-jpa提供数据库访问能力。spring-boot-starter-security用于认证和授权。spring-boot-starter-validation参数校验。spring-boot-starter-data-redis缓存和 Token 存储。flyway-core 和 flyway-database-postgresql数据库版本迁移。spring-boot-starter-actuator健康检查和监控端点。postgresqlPostgreSQL 驱动。依赖版本不需要手动写Spring Boot 的父工程会统一管理。这里给出的 bootVersion 只是一个示例实际项目要以当时发布版本为准。2.3 配置管理区分本地、测试、生产Spring Boot 支持多 Profile 配置。常见做法是保留一个主配置application.yml再按环境拆分application-local.yml、application-test.yml、application-prod.yml。主配置可以放通用项spring: application: name: startup profiles: active: ${SPRING_PROFILES_ACTIVE:local} jpa: hibernate: ddl-auto: validate open-in-view: false flyway: enabled: true本地配置放本地连接信息spring: datasource: url: jdbc:postgresql://localhost:5432/startup username: startup password: startup123 data: redis: host: localhost port: 6379 server: port: 8080生产配置不要直接写密码在文件里要使用环境变量占位符spring: datasource: url: ${DB_URL} username: ${DB_USERNAME} password: ${DB_PASSWORD} data: redis: host: ${REDIS_HOST} port: ${REDIS_PORT}这一步的关键是环境变量由部署平台注入而不是写死在代码仓库。否则数据库口令一旦泄露影响面会很大。3. 核心服务实现用最小闭环跑通认证、业务和存储3.1 用户认证模块从 Session 到 Token早期产品通常需要登录注册。单体应用里用 Session 也能实现认证但如果后续要支持小程序、App、或前后端分离Token 方案会更方便。常见的 Token 方案是基于 JWT但要注意 JWT 一旦签发在过期前无法主动撤销。所以可以把 Token 的jti字段存到 Redis利用 Redis 过期时间实现登出和踢人。下面是一个 JWT 工具的核心思路public class JwtTokenService { private final SecretKey key; private final Duration ttl; public JwtTokenService(String secret, Duration ttl) { this.key Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8)); this.ttl ttl; } public String generateToken(String userId) { Instant now Instant.now(); return Jwts.builder() .subject(userId) .id(UUID.randomUUID().toString()) .issuedAt(Date.from(now)) .expiration(Date.from(now.plus(ttl))) .signWith(key) .compact(); } public JwsClaims parseToken(String token) { return Jwts.parserBuilder() .setSigningKey(key) .build() .parseClaimsJws(token); } }这里面的secret必须足够长至少 32 字节。生产环境不要把密钥硬编码可以从环境变量读取。签发 Token 后把它存到 Rediskey可以是token:{jti}过期时间与 JWT 保持一致。认证过滤器要做的事情只有三步从请求头里取Authorization: Bearer token。解析 Token校验签名和过期时间。从 Redis 确认jti仍然有效然后把 userId 放入 SecurityContext。这套逻辑虽然代码量比 Session 模式多一点但它天然适合多端共用同一个后端。3.2 业务模块以“用户资料”为例写一个 API认证解决的是“你是谁”业务接口解决的是“你能做什么”。以一个简单的用户资料接口为例演示完整分层。先定义实体Entity Table(name user_profile) public class UserProfile { Id private Long id; private String nickname; private String avatar; private String bio; CreationTimestamp private Instant createdAt; UpdateTimestamp private Instant updatedAt; }再写 Repositorypublic interface UserProfileRepository extends JpaRepositoryUserProfile, Long { }Service 负责业务规则。比如更新资料前判断昵称长度Service public class UserProfileService { private final UserProfileRepository userProfileRepository; public UserProfileService(UserProfileRepository userProfileRepository) { this.userProfileRepository userProfileRepository; } Transactional public UserProfile update(Long userId, UpdateProfileRequest request) { UserProfile profile userProfileRepository.findById(userId) .orElseThrow(() - new BusinessException(profile not found)); if (request.nickname() ! null) { if (request.nickname().length() 2 || request.nickname().length() 20) { throw new BusinessException(nickname length must be between 2 and 20); } profile.setNickname(request.nickname()); } if (request.avatar() ! null) { profile.setAvatar(request.avatar()); } if (request.bio() ! null request.bio().length() 200) { profile.setBio(request.bio()); } return userProfileRepository.save(profile); } }Controller 只做参数接收和返回包装RestController RequestMapping(/api/profiles) public class UserProfileController { private final UserProfileService userProfileService; public UserProfileController(UserProfileService userProfileService) { this.userProfileService userProfileService; } GetMapping(/me) public UserProfile currentProfile(Authentication authentication) { Long userId Long.valueOf(authentication.getName()); return userProfileService.get(userId); } PutMapping(/me) public UserProfile updateProfile( Authentication authentication, Valid RequestBody UpdateProfileRequest request) { Long userId Long.valueOf(authentication.getName()); return userProfileService.update(userId, request); } }这里的Authentication.getName()在认证过滤器里被设置为当前用户 IDController 不需要再次解析 Token。3.3 数据访问与迁移数据库版本化快速迭代阶段最怕手工在数据库里执行 DDL。今天改一次表结构明天加一个字段时间久了没人知道表是什么时候变的。推荐使用 Flyway 做数据库版本迁移。在src/main/resources/db/migration目录下创建第一个迁移文件-- V1__create_user_profile.sql CREATE TABLE user_profile ( id BIGINT PRIMARY KEY, nickname VARCHAR(50) NOT NULL, avatar VARCHAR(255), bio VARCHAR(200), created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP );应用启动时Flyway 会检查flyway_schema_history表。如果没有执行过 V1就执行它并在历史表中登记。之后新增表或修改字段不要再改 V1 文件而是新建 V2 文件-- V2__add_user_status.sql ALTER TABLE user_profile ADD COLUMN status VARCHAR(20) NOT NULL DEFAULT ACTIVE;这样做的理由是已经执行过的迁移不能被修改否则会破坏所有环境的基线。本地想重置可以清库重建生产环境必须通过新增迁移文件变更结构。4. 容器化与一键启动让新成员三分钟跑起来4.1 Dockerfile 编写要点容器化的目的不只是部署更重要的是让本地、测试、生产环境保持一致。用 Docker 打包 Spring Boot 应用推荐使用多阶段构建先编译再生成精简运行镜像。# 构建阶段 FROM maven:3.9-eclipse-temurin-17 AS builder WORKDIR /app COPY pom.xml . RUN mvn dependency:go-offline COPY src ./src RUN mvn package -DskipTests # 运行阶段 FROM eclipse-temurin:17-jre WORKDIR /app COPY --frombuilder /app/target/startup-0.0.1-SNAPSHOT.jar app.jar EXPOSE 8080 ENTRYPOINT [java, -jar, app.jar]这里把依赖下载单独放在COPY pom.xml之后目的是让 Maven 利用 Docker 层缓存。只要 pom.xml 不变后续构建不需要重新下载依赖。需要注意不要直接使用maven镜像运行 jar这样镜像体积会大很多。多阶段构建最终只保留 JRE 和 jar 包。4.2 用 docker-compose 编排应用与依赖本地开发时希望一条命令同时启动数据库、Redis 和应用。可以在docker-compose.yml中增加 app 服务services: postgres: image: postgres:16 environment: POSTGRES_DB: startup POSTGRES_USER: startup POSTGRES_PASSWORD: startup123 ports: - 5432:5432 volumes: - postgres-data:/var/lib/postgresql/data redis: image: redis:7 ports: - 6379:6379 app: build: . ports: - 8080:8080 environment: SPRING_PROFILES_ACTIVE: prod DB_URL: jdbc:postgresql://postgres:5432/startup DB_USERNAME: startup DB_PASSWORD: startup123 REDIS_HOST: redis REDIS_PORT: 6379 depends_on: - postgres - redisdepends_on只保证容器启动顺序不保证服务真正可用。应用启动时如果数据库还没准备好Spring Boot 会重试连接一般等几秒就能恢复。如果等不到可以在镜像入口加一个等待脚本但不要过度设计。4.3 本地启动与验证在执行 docker compose 前先在本地直接用 Maven 启动mvn spring-boot:run看到如下日志说明启动成功Tomcat started on port 8080 Started StartupApplication in 8.21 seconds然后调用健康检查接口curl http://localhost:8080/actuator/health预期返回{status:UP}注册一个用户并登录curl -X POST http://localhost:8080/api/auth/register \ -H Content-Type: application/json \ -d {username:demo,password:123456}如果接口返回用户 ID 或 Token说明认证、数据库、迁移链路都已跑通。5. 部署与可观测性从开发机到云服务器5.1 生产环境的最小部署架构生产环境在初期不复杂一台云服务器就可以承载。建议部署顺序是在服务器安装 Docker 和 Docker Compose。把应用镜像推送到镜像仓库或直接在服务器上执行构建。使用 Nginx 做反向代理和 HTTPS 终止。数据库和 Redis 可以与应用同机但数据目录要挂载到宿主机独立磁盘。最小架构图可以用文字描述外部请求到达 NginxNginx 将/api/转发到应用容器将静态资源直接返回。应用连接内部网络中的 PostgreSQL 和 Redis。这样一个节点足够支撑早期日活几千到几万的业务。学习环境与生产环境差异如下关注点学习环境生产环境配置写在本地文件使用环境变量或配置中心数据库可随时清空必须定期备份并验证恢复日志控制台直接看收集到统一日志平台保留一段时间权限本机管理员分角色、分密钥、最小权限监控不需要需要有健康检查和告警回滚重启即可需要保留上一个镜像和数据库回滚预案5.2 日志采集与错误追踪上线后最大的问题是“用户说接口报错但登录服务器看不到日志”。所以日志一定要统一格式方便检索。推荐在 logback 配置中定义 JSON 格式或带 traceId 的文本格式。最简单的方式是每个请求生成一个 traceId放入 MDCComponent public class TraceIdFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { String traceId UUID.randomUUID().toString(); MDC.put(traceId, traceId); try { chain.doFilter(request, response); } finally { MDC.remove(traceId); } } }日志配置里加上%X{traceId}pattern%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%X{traceId}] %logger{36} - %msg%n/pattern这样报错日志和访问日志可以通过同一个 traceId 串联排查问题时能快速定位一个请求走过了哪些类、报了什么错。5.3 健康检查与告警spring-boot-starter-actuator已经提供健康检查能力。生产环境需要把数据库和 Redis 的健康检查打开并设置敏感端点不对外暴露。配置示例management: endpoints: web: exposure: include: health,info endpoint: health: show-details: when_authorized probes: enabled: true然后用一个外部脚本定时请求健康检查地址curl -fsS http://localhost:8080/actuator/health || echo service down如果希望接入钉钉、飞书或企业微信告警可以在检测脚本里调用 Webhook。这里只给出思路实际地址和 token 需要团队配置到自己的渠道。6. 常见问题排查接口慢、数据不一致、启动失败6.1 数据库连接池耗尽现象应用日志频繁出现Connection is not available, request timed out数据库 CPU 不高但接口偶发超时。常见原因慢 SQL 占满连接池。连接池配置过小。代码里事务没有正确释放连接。某个接口循环调用数据库单次请求占用多个连接。排查顺序查看连接池当前活跃数SELECT count(*) FROM pg_stat_activity;查看是否存在长时间未提交事务SELECT pid, state, now() - xact_start AS duration, query FROM pg_stat_activity WHERE state active ORDER BY duration DESC;在应用日志里开启 SQL 打印观察是否有明显慢 SQL。处理建议spring: datasource: hikari: maximum-pool-size: 10 minimum-idle: 2 connection-timeout: 3000连接池不是越大越好。4 核 8G 的应用容器10 到 15 个连接通常足够。连接数过多反而会增加数据库切换上下文开销。6.2 Redis 缓存穿透与击穿现象某个热点数据第一次请求时缓存没有所有请求同时打到数据库。常见场景和方案缓存穿透查询一个一定不存在的 key每次都会访问数据库。解决方式是对空值也做短时间缓存或者使用布隆过滤器。缓存击穿某个热点 key 过期大量请求同时回源。解决方式是加互斥锁只允许一个请求查库并回填缓存。缓存雪崩大量 key 在同一时间段过期。解决方式是过期时间加随机抖动。示例代码片段public String getProfile(Long userId) { String key profile: userId; String cached redisTemplate.opsForValue().get(key); if (cached ! null) { return cached; } String lockKey lock:profile: userId; Boolean locked redisTemplate.opsForValue().setIfAbsent(lockKey, 1, Duration.ofSeconds(5)); if (Boolean.TRUE.equals(locked)) { try { String value loadFromDb(userId); redisTemplate.opsForValue().set(key, value, Duration.ofSeconds(300 RandomUtils.nextInt(30))); return value; } finally { redisTemplate.delete(lockKey); } } else { // 等待一小段时间后重试或者直接查库 Thread.sleep(100); return getProfile(userId); } }这里使用了简单的 Redis lock但要注意锁释放和过期时间设置的细节。生产环境可以使用 Redisson 等成熟客户端避免自己实现分布式锁的边界问题。6.3 端口、网络与容器互相访问问题现象本地能访问接口但容器里访问不到数据库或者服务器上curl localhost:8080有响应外部却无法访问。排查顺序确认应用容器是否监听在0.0.0.0:8080而不是127.0.0.1:8080。Docker 端口映射时宿主机访问容器需要通过映射端口。使用docker logs container查看应用启动日志。进入容器测试网络连通性docker exec -it app-container ping redis docker exec -it app-container curl http://localhost:8080/actuator/health检查 Nginx 配置文件、云服务器安全组、防火墙规则。现象可能原因检查命令处理方式外部无法访问 8080云安全组未放行端口云控制台查看入方向规则只放行 80/443应用端口不直接暴露容器内无法连接数据库数据库地址写成了 localhostdocker exec内使用服务名连接改为 compose 中的服务名postgres健康检查 503数据库或 Redis 未就绪docker logs db-container等待服务启动后重启应用这里最关键的原则是越是环境变化导致的报错越要先确认“配置里的地址在当前运行环境里是否可达”。7. 工程化最佳实践与后续演进7.1 代码审查清单三个月快速迭代不代表不需要代码审查。下面是一份可直接使用的检查清单是否在 Controller 里处理了异常并返回统一种错误结构。是否使用参数校验注解而不是在 Service 里手工判断所有字段。是否在事务方法里做了远程调用或外部 IO。新增字段时是否有数据库迁移文件。是否把密码、Token、数据库口令写在配置仓库里。是否打印了可追踪的 traceId 和关键业务参数。是否在 Redis 缓存和数据库之间考虑了一致性要求。是否添加了必要的单元测试或接口测试。这些检查点不需要一次全部完成但每次提交 PR 前至少对照一遍能避免大量低级问题。7.2 上线前检查清单上线不是“代码能跑”就算完成。建议发布前逐项确认数据库备份是否完成迁移文件是否已在测试环境执行过。生产环境配置是否全部来自环境变量有没有残留本地地址。SSL 证书是否有效HTTP 是否自动跳转 HTTPS。健康检查接口是否无鉴权暴露日志是否包含敏感信息。回滚方案是否明确旧镜像能否直接启动数据库迁移是否向后兼容。监控告警是否配置完毕负责人是谁。是否准备好对外接口文档和联调联系人。其中“数据库迁移是否向后兼容”最容易被忽略。比如新增的字段如果有NOT NULL而代码还没发布旧代码插入记录就会失败。正确的做法是先加可空字段发布新代码后再在下一个版本收紧约束。7.3 扩展方向什么时候引入微服务、消息队列很多团队在三个月后会面临业务规模增长但不要因为用户量大了就立刻拆微服务。建议按这个顺序演进先拆分数据库读写或把静态资源迁移到对象存储。当某个模块需要独立扩容时再拆分第一个服务。当出现异步任务发通知、生成报表、处理上传文件时引入消息队列。当服务数量超过 5 个时再考虑服务发现、网关、全链路追踪和 Kubernetes。过早引入这些组件会让团队主要精力从业务功能转移到基础设施维护上。对快速成长的项目来说这往往不是技术问题而是资源分配问题。技术架构没有银弹。三个月跑通业务的关键不在于用了多新潮的框架而在于每一层都简单可替换、可监控、可排查。后续每一次架构调整都应该从真实业务痛点出发而不是为了技术上的完美。 初创团队快速上线：单体架构、容器化部署与运维实践
一家新公司从成立到产品上线留给技术团队的窗口期通常很短。业务侧已经验证了需求客户在等接口运营在催后台而后端可能还只有一个原型仓库。这个阶段最容易犯的错误是盲目追求架构复杂度一上来就拆微服务、引入 Kubernetes、设计分布式事务。实际上三个月内要交付的是稳定、可维护、能快速迭代的骨架而不是一个理论上无限扩展的庞然大物。下面这套搭建路径适合刚起步的创业团队参考也适合个人开发者搭自己产品时使用。它围绕一台应用服务器、一个关系数据库、一个缓存服务展开先跑通认证、业务和数据迁移再逐步加入容器化部署、日志监控和故障排查手段。1. 先想清楚快速上线阶段技术架构要抓住哪几条主线1.1 从业务诉求倒推技术选型很多团队在选型时先看技术热度再看团队熟悉度最后才考虑业务阶段这个顺序应该反过来。三个月的交付期里最值钱的不是技术栈新不新而是问题能不能快速定位、新成员能不能快速上手、依赖组件能不能在云服务器上低成本跑起来。选型要从三个问题倒推产品的主要用户是谁预计流量规模多大。早期通常只有几千到几万用户一台 4 核 8G 服务器已经足够承载业务主体。团队最熟悉哪门语言和框架。不建议在起步阶段引入全员都没接触过的语言即使它再适合所谓高并发也会在招聘、培训和排错上付出额外成本。业务是重逻辑还是重数据。如果核心是下单、对账、权限那么关系数据库一定是主存储如果核心是文案、图片、外部 API 转发那么对数据库一致性的要求可以降低但对外部服务稳定性要求会更高。常见技术选型可以做如下对比技术组件典型选型用途早期成本后端框架Spring Boot 或 Node.js/NestJS提供 HTTP API、业务逻辑低关系数据库PostgreSQL 或 MySQL用户、订单、配置等结构化数据低缓存Redis会话、验证码、热点数据低对象存储云厂商 OSS/S3 兼容服务图片、文件、静态资源按量付费部署环境Docker Docker Compose本地与生产一致化低反向代理Nginx域名转发、SSL 终止、静态资源服务低这套选型不是唯一答案但足够稳。它不需要一开始就维护多套环境、多个服务实例也能在业务量上来之后平滑扩展。1.2 先搭单体应用不要一上来就拆微服务微服务解决的是团队扩大、模块独立发布、故障隔离等问题但它也会引入服务发现、配置中心、分布式事务、链路追踪等额外复杂度。对三个月上线目标来说这些复杂度会直接吃掉排期。正确做法是做一个“模块化单体”一个应用工程按业务域拆包。不跨模块直接调用数据库表而是通过 Service 接口。模块间通过普通 Java 方法调用而不是 HTTP 调用。预留独立的对外 API 入口但内部保持单体部署。比如按用户、内容、订单三个域拆包com.example.startup ├── common ├── user ├── content └── order每个业务域内部可以有自己的 controller、service、repository。这样未来某个域确实需要拆分时可以直接把对应包抽成独立服务而不用重写业务逻辑。1.3 明确开发、测试、运维的工作边界早期团队可能没有专职运维开发也兼任测试。此时最怕的是职责不清导致生产环境变成“谁都能动谁都不负责”。建议划分如下开发负责本地环境、代码实现、单元测试、接口自测。测试负责测试环境验证、回归用例、线上冒烟测试。运维负责服务器初始化、部署脚本、日志备份、监控告警。如果没人专职至少指定一个人负责而不是轮流值班。任何生产环境变更都要有记录哪怕是执行一条 SQL也要写明时间、原因、操作人、回滚方式。这个顺序看起来简单但很多事故都源于生产环境变更没有记录。早期哪怕用一张在线表格记录也比完全无序强。2. 环境准备与依赖版本一套能复现的本地开发环境2.1 基础环境清单快速上线阶段环境问题最容易造成“本地能跑服务器跑不了”。要减少这类问题最好把所有基础环境写进项目 README并用脚本或容器固定下来。以 Java 技术栈为例本地环境建议如下组件用途验证命令JDK 17 或 21编译和运行 Spring Bootjava -versionMaven 或 Gradle依赖管理mvn -vDocker运行中间件和部署docker --versionDocker Compose编排本地中间件docker compose versionPostgreSQL 或 MySQL 客户端连接数据库执行 SQLpsql --versionRedis 客户端查看缓存内容redis-cli ping如果你不想本地安装数据库和 Redis最简单的方式是用 Docker 启动中间件。下面是一个本地中间件编排示例services: postgres: image: postgres:16 container_name: startup-postgres environment: POSTGRES_DB: startup POSTGRES_USER: startup POSTGRES_PASSWORD: startup123 ports: - 5432:5432 volumes: - postgres-data:/var/lib/postgresql/data redis: image: redis:7 container_name: startup-redis ports: - 6379:6379 volumes: postgres-data:启动命令docker compose up -d检查结果docker ps如果容器状态是 Up说明数据库和缓存都已启动。这里要注意容器里的数据默认写到 named volume删除容器不会丢数据。如果使用不带 volume 的方式删除容器后数据会丢失。2.2 初始化 Spring Boot 项目使用 Spring Initializr 初始化项目最简单。如果是命令行操作可以用 curl 生成基础工程curl https://start.spring.io/starter.zip \ -d typemaven-project \ -d languagejava \ -d bootVersion3.3.0 \ -d groupIdcom.example \ -d artifactIdstartup \ -d namestartup \ -d packageNamecom.example.startup \ -d dependenciesweb,data-jpa,security,validation,redis,flyway,actuator,postgresql \ -o startup.zip解压后导入 IDE。关键依赖说明spring-boot-starter-web提供 HTTP API。spring-boot-starter-data-jpa提供数据库访问能力。spring-boot-starter-security用于认证和授权。spring-boot-starter-validation参数校验。spring-boot-starter-data-redis缓存和 Token 存储。flyway-core 和 flyway-database-postgresql数据库版本迁移。spring-boot-starter-actuator健康检查和监控端点。postgresqlPostgreSQL 驱动。依赖版本不需要手动写Spring Boot 的父工程会统一管理。这里给出的 bootVersion 只是一个示例实际项目要以当时发布版本为准。2.3 配置管理区分本地、测试、生产Spring Boot 支持多 Profile 配置。常见做法是保留一个主配置application.yml再按环境拆分application-local.yml、application-test.yml、application-prod.yml。主配置可以放通用项spring: application: name: startup profiles: active: ${SPRING_PROFILES_ACTIVE:local} jpa: hibernate: ddl-auto: validate open-in-view: false flyway: enabled: true本地配置放本地连接信息spring: datasource: url: jdbc:postgresql://localhost:5432/startup username: startup password: startup123 data: redis: host: localhost port: 6379 server: port: 8080生产配置不要直接写密码在文件里要使用环境变量占位符spring: datasource: url: ${DB_URL} username: ${DB_USERNAME} password: ${DB_PASSWORD} data: redis: host: ${REDIS_HOST} port: ${REDIS_PORT}这一步的关键是环境变量由部署平台注入而不是写死在代码仓库。否则数据库口令一旦泄露影响面会很大。3. 核心服务实现用最小闭环跑通认证、业务和存储3.1 用户认证模块从 Session 到 Token早期产品通常需要登录注册。单体应用里用 Session 也能实现认证但如果后续要支持小程序、App、或前后端分离Token 方案会更方便。常见的 Token 方案是基于 JWT但要注意 JWT 一旦签发在过期前无法主动撤销。所以可以把 Token 的jti字段存到 Redis利用 Redis 过期时间实现登出和踢人。下面是一个 JWT 工具的核心思路public class JwtTokenService { private final SecretKey key; private final Duration ttl; public JwtTokenService(String secret, Duration ttl) { this.key Keys.hmacShaKeyFor(secret.getBytes(StandardCharsets.UTF_8)); this.ttl ttl; } public String generateToken(String userId) { Instant now Instant.now(); return Jwts.builder() .subject(userId) .id(UUID.randomUUID().toString()) .issuedAt(Date.from(now)) .expiration(Date.from(now.plus(ttl))) .signWith(key) .compact(); } public JwsClaims parseToken(String token) { return Jwts.parserBuilder() .setSigningKey(key) .build() .parseClaimsJws(token); } }这里面的secret必须足够长至少 32 字节。生产环境不要把密钥硬编码可以从环境变量读取。签发 Token 后把它存到 Rediskey可以是token:{jti}过期时间与 JWT 保持一致。认证过滤器要做的事情只有三步从请求头里取Authorization: Bearer token。解析 Token校验签名和过期时间。从 Redis 确认jti仍然有效然后把 userId 放入 SecurityContext。这套逻辑虽然代码量比 Session 模式多一点但它天然适合多端共用同一个后端。3.2 业务模块以“用户资料”为例写一个 API认证解决的是“你是谁”业务接口解决的是“你能做什么”。以一个简单的用户资料接口为例演示完整分层。先定义实体Entity Table(name user_profile) public class UserProfile { Id private Long id; private String nickname; private String avatar; private String bio; CreationTimestamp private Instant createdAt; UpdateTimestamp private Instant updatedAt; }再写 Repositorypublic interface UserProfileRepository extends JpaRepositoryUserProfile, Long { }Service 负责业务规则。比如更新资料前判断昵称长度Service public class UserProfileService { private final UserProfileRepository userProfileRepository; public UserProfileService(UserProfileRepository userProfileRepository) { this.userProfileRepository userProfileRepository; } Transactional public UserProfile update(Long userId, UpdateProfileRequest request) { UserProfile profile userProfileRepository.findById(userId) .orElseThrow(() - new BusinessException(profile not found)); if (request.nickname() ! null) { if (request.nickname().length() 2 || request.nickname().length() 20) { throw new BusinessException(nickname length must be between 2 and 20); } profile.setNickname(request.nickname()); } if (request.avatar() ! null) { profile.setAvatar(request.avatar()); } if (request.bio() ! null request.bio().length() 200) { profile.setBio(request.bio()); } return userProfileRepository.save(profile); } }Controller 只做参数接收和返回包装RestController RequestMapping(/api/profiles) public class UserProfileController { private final UserProfileService userProfileService; public UserProfileController(UserProfileService userProfileService) { this.userProfileService userProfileService; } GetMapping(/me) public UserProfile currentProfile(Authentication authentication) { Long userId Long.valueOf(authentication.getName()); return userProfileService.get(userId); } PutMapping(/me) public UserProfile updateProfile( Authentication authentication, Valid RequestBody UpdateProfileRequest request) { Long userId Long.valueOf(authentication.getName()); return userProfileService.update(userId, request); } }这里的Authentication.getName()在认证过滤器里被设置为当前用户 IDController 不需要再次解析 Token。3.3 数据访问与迁移数据库版本化快速迭代阶段最怕手工在数据库里执行 DDL。今天改一次表结构明天加一个字段时间久了没人知道表是什么时候变的。推荐使用 Flyway 做数据库版本迁移。在src/main/resources/db/migration目录下创建第一个迁移文件-- V1__create_user_profile.sql CREATE TABLE user_profile ( id BIGINT PRIMARY KEY, nickname VARCHAR(50) NOT NULL, avatar VARCHAR(255), bio VARCHAR(200), created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP );应用启动时Flyway 会检查flyway_schema_history表。如果没有执行过 V1就执行它并在历史表中登记。之后新增表或修改字段不要再改 V1 文件而是新建 V2 文件-- V2__add_user_status.sql ALTER TABLE user_profile ADD COLUMN status VARCHAR(20) NOT NULL DEFAULT ACTIVE;这样做的理由是已经执行过的迁移不能被修改否则会破坏所有环境的基线。本地想重置可以清库重建生产环境必须通过新增迁移文件变更结构。4. 容器化与一键启动让新成员三分钟跑起来4.1 Dockerfile 编写要点容器化的目的不只是部署更重要的是让本地、测试、生产环境保持一致。用 Docker 打包 Spring Boot 应用推荐使用多阶段构建先编译再生成精简运行镜像。# 构建阶段 FROM maven:3.9-eclipse-temurin-17 AS builder WORKDIR /app COPY pom.xml . RUN mvn dependency:go-offline COPY src ./src RUN mvn package -DskipTests # 运行阶段 FROM eclipse-temurin:17-jre WORKDIR /app COPY --frombuilder /app/target/startup-0.0.1-SNAPSHOT.jar app.jar EXPOSE 8080 ENTRYPOINT [java, -jar, app.jar]这里把依赖下载单独放在COPY pom.xml之后目的是让 Maven 利用 Docker 层缓存。只要 pom.xml 不变后续构建不需要重新下载依赖。需要注意不要直接使用maven镜像运行 jar这样镜像体积会大很多。多阶段构建最终只保留 JRE 和 jar 包。4.2 用 docker-compose 编排应用与依赖本地开发时希望一条命令同时启动数据库、Redis 和应用。可以在docker-compose.yml中增加 app 服务services: postgres: image: postgres:16 environment: POSTGRES_DB: startup POSTGRES_USER: startup POSTGRES_PASSWORD: startup123 ports: - 5432:5432 volumes: - postgres-data:/var/lib/postgresql/data redis: image: redis:7 ports: - 6379:6379 app: build: . ports: - 8080:8080 environment: SPRING_PROFILES_ACTIVE: prod DB_URL: jdbc:postgresql://postgres:5432/startup DB_USERNAME: startup DB_PASSWORD: startup123 REDIS_HOST: redis REDIS_PORT: 6379 depends_on: - postgres - redisdepends_on只保证容器启动顺序不保证服务真正可用。应用启动时如果数据库还没准备好Spring Boot 会重试连接一般等几秒就能恢复。如果等不到可以在镜像入口加一个等待脚本但不要过度设计。4.3 本地启动与验证在执行 docker compose 前先在本地直接用 Maven 启动mvn spring-boot:run看到如下日志说明启动成功Tomcat started on port 8080 Started StartupApplication in 8.21 seconds然后调用健康检查接口curl http://localhost:8080/actuator/health预期返回{status:UP}注册一个用户并登录curl -X POST http://localhost:8080/api/auth/register \ -H Content-Type: application/json \ -d {username:demo,password:123456}如果接口返回用户 ID 或 Token说明认证、数据库、迁移链路都已跑通。5. 部署与可观测性从开发机到云服务器5.1 生产环境的最小部署架构生产环境在初期不复杂一台云服务器就可以承载。建议部署顺序是在服务器安装 Docker 和 Docker Compose。把应用镜像推送到镜像仓库或直接在服务器上执行构建。使用 Nginx 做反向代理和 HTTPS 终止。数据库和 Redis 可以与应用同机但数据目录要挂载到宿主机独立磁盘。最小架构图可以用文字描述外部请求到达 NginxNginx 将/api/转发到应用容器将静态资源直接返回。应用连接内部网络中的 PostgreSQL 和 Redis。这样一个节点足够支撑早期日活几千到几万的业务。学习环境与生产环境差异如下关注点学习环境生产环境配置写在本地文件使用环境变量或配置中心数据库可随时清空必须定期备份并验证恢复日志控制台直接看收集到统一日志平台保留一段时间权限本机管理员分角色、分密钥、最小权限监控不需要需要有健康检查和告警回滚重启即可需要保留上一个镜像和数据库回滚预案5.2 日志采集与错误追踪上线后最大的问题是“用户说接口报错但登录服务器看不到日志”。所以日志一定要统一格式方便检索。推荐在 logback 配置中定义 JSON 格式或带 traceId 的文本格式。最简单的方式是每个请求生成一个 traceId放入 MDCComponent public class TraceIdFilter implements Filter { Override public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { String traceId UUID.randomUUID().toString(); MDC.put(traceId, traceId); try { chain.doFilter(request, response); } finally { MDC.remove(traceId); } } }日志配置里加上%X{traceId}pattern%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%X{traceId}] %logger{36} - %msg%n/pattern这样报错日志和访问日志可以通过同一个 traceId 串联排查问题时能快速定位一个请求走过了哪些类、报了什么错。5.3 健康检查与告警spring-boot-starter-actuator已经提供健康检查能力。生产环境需要把数据库和 Redis 的健康检查打开并设置敏感端点不对外暴露。配置示例management: endpoints: web: exposure: include: health,info endpoint: health: show-details: when_authorized probes: enabled: true然后用一个外部脚本定时请求健康检查地址curl -fsS http://localhost:8080/actuator/health || echo service down如果希望接入钉钉、飞书或企业微信告警可以在检测脚本里调用 Webhook。这里只给出思路实际地址和 token 需要团队配置到自己的渠道。6. 常见问题排查接口慢、数据不一致、启动失败6.1 数据库连接池耗尽现象应用日志频繁出现Connection is not available, request timed out数据库 CPU 不高但接口偶发超时。常见原因慢 SQL 占满连接池。连接池配置过小。代码里事务没有正确释放连接。某个接口循环调用数据库单次请求占用多个连接。排查顺序查看连接池当前活跃数SELECT count(*) FROM pg_stat_activity;查看是否存在长时间未提交事务SELECT pid, state, now() - xact_start AS duration, query FROM pg_stat_activity WHERE state active ORDER BY duration DESC;在应用日志里开启 SQL 打印观察是否有明显慢 SQL。处理建议spring: datasource: hikari: maximum-pool-size: 10 minimum-idle: 2 connection-timeout: 3000连接池不是越大越好。4 核 8G 的应用容器10 到 15 个连接通常足够。连接数过多反而会增加数据库切换上下文开销。6.2 Redis 缓存穿透与击穿现象某个热点数据第一次请求时缓存没有所有请求同时打到数据库。常见场景和方案缓存穿透查询一个一定不存在的 key每次都会访问数据库。解决方式是对空值也做短时间缓存或者使用布隆过滤器。缓存击穿某个热点 key 过期大量请求同时回源。解决方式是加互斥锁只允许一个请求查库并回填缓存。缓存雪崩大量 key 在同一时间段过期。解决方式是过期时间加随机抖动。示例代码片段public String getProfile(Long userId) { String key profile: userId; String cached redisTemplate.opsForValue().get(key); if (cached ! null) { return cached; } String lockKey lock:profile: userId; Boolean locked redisTemplate.opsForValue().setIfAbsent(lockKey, 1, Duration.ofSeconds(5)); if (Boolean.TRUE.equals(locked)) { try { String value loadFromDb(userId); redisTemplate.opsForValue().set(key, value, Duration.ofSeconds(300 RandomUtils.nextInt(30))); return value; } finally { redisTemplate.delete(lockKey); } } else { // 等待一小段时间后重试或者直接查库 Thread.sleep(100); return getProfile(userId); } }这里使用了简单的 Redis lock但要注意锁释放和过期时间设置的细节。生产环境可以使用 Redisson 等成熟客户端避免自己实现分布式锁的边界问题。6.3 端口、网络与容器互相访问问题现象本地能访问接口但容器里访问不到数据库或者服务器上curl localhost:8080有响应外部却无法访问。排查顺序确认应用容器是否监听在0.0.0.0:8080而不是127.0.0.1:8080。Docker 端口映射时宿主机访问容器需要通过映射端口。使用docker logs container查看应用启动日志。进入容器测试网络连通性docker exec -it app-container ping redis docker exec -it app-container curl http://localhost:8080/actuator/health检查 Nginx 配置文件、云服务器安全组、防火墙规则。现象可能原因检查命令处理方式外部无法访问 8080云安全组未放行端口云控制台查看入方向规则只放行 80/443应用端口不直接暴露容器内无法连接数据库数据库地址写成了 localhostdocker exec内使用服务名连接改为 compose 中的服务名postgres健康检查 503数据库或 Redis 未就绪docker logs db-container等待服务启动后重启应用这里最关键的原则是越是环境变化导致的报错越要先确认“配置里的地址在当前运行环境里是否可达”。7. 工程化最佳实践与后续演进7.1 代码审查清单三个月快速迭代不代表不需要代码审查。下面是一份可直接使用的检查清单是否在 Controller 里处理了异常并返回统一种错误结构。是否使用参数校验注解而不是在 Service 里手工判断所有字段。是否在事务方法里做了远程调用或外部 IO。新增字段时是否有数据库迁移文件。是否把密码、Token、数据库口令写在配置仓库里。是否打印了可追踪的 traceId 和关键业务参数。是否在 Redis 缓存和数据库之间考虑了一致性要求。是否添加了必要的单元测试或接口测试。这些检查点不需要一次全部完成但每次提交 PR 前至少对照一遍能避免大量低级问题。7.2 上线前检查清单上线不是“代码能跑”就算完成。建议发布前逐项确认数据库备份是否完成迁移文件是否已在测试环境执行过。生产环境配置是否全部来自环境变量有没有残留本地地址。SSL 证书是否有效HTTP 是否自动跳转 HTTPS。健康检查接口是否无鉴权暴露日志是否包含敏感信息。回滚方案是否明确旧镜像能否直接启动数据库迁移是否向后兼容。监控告警是否配置完毕负责人是谁。是否准备好对外接口文档和联调联系人。其中“数据库迁移是否向后兼容”最容易被忽略。比如新增的字段如果有NOT NULL而代码还没发布旧代码插入记录就会失败。正确的做法是先加可空字段发布新代码后再在下一个版本收紧约束。7.3 扩展方向什么时候引入微服务、消息队列很多团队在三个月后会面临业务规模增长但不要因为用户量大了就立刻拆微服务。建议按这个顺序演进先拆分数据库读写或把静态资源迁移到对象存储。当某个模块需要独立扩容时再拆分第一个服务。当出现异步任务发通知、生成报表、处理上传文件时引入消息队列。当服务数量超过 5 个时再考虑服务发现、网关、全链路追踪和 Kubernetes。过早引入这些组件会让团队主要精力从业务功能转移到基础设施维护上。对快速成长的项目来说这往往不是技术问题而是资源分配问题。技术架构没有银弹。三个月跑通业务的关键不在于用了多新潮的框架而在于每一层都简单可替换、可监控、可排查。后续每一次架构调整都应该从真实业务痛点出发而不是为了技术上的完美。