Java远程图片下载与动态水印实现：从ImageIO到Graphics2D实战

给远程图片加水印，是我前后做过几个图片服务之后才真正摸熟的需求。平时说“加载图片、处理图片、保存图片”就是三步，可真要把“根据图片url下载图片并动态添加水印”做成一个稳定可用的功能，超时、防盗链、透明通道、中文字体、内存溢出这些问题就会一个接一个冒出来。这篇文章适合三类读者：一是业务上要给远程图片快速加水印的开发者，二是想搞清楚 ImageIO 和 Graphics2D 怎么配合的人，三是准备把图片下载和处理封装成一个小服务的同学。

我按真实开发顺序来写，不整虚的：先把 URL 下载做成能抗并发、能限制大小、能处理重定向的工具方法，再把图片解码成 BufferedImage，然后重点讲动态水印的绘制细节，最后聊输出格式、内存控制和常见坑。代码可以直接抄，里面的踩坑经验也能省你不少调试时间。

1. 需求拆解与技术选型：为什么下载和水印要放一起做

1.1 这类需求一般出现在哪些场景里

先说场景，免得有人觉得这只是个练习题。我在实际项目里见过至少四类地方会用到“远程图片下载 + 动态水印”：

• 内容平台做预览图。用户没登录，或者还不是会员，服务端拉取原图后，在右上角打上账号名、访问时间这类动态文字，再输出给前端，防止图片被直接下载后到处传播。
• 电商和营销系统。供应商图片放在图床或云端，系统按活动批次抓取后叠加价格、折扣、活动名称。每次活动内容都不同，水印内容自然不能用代码写死。
• 素材库归集。内部系统把外链图片转存到自己的存储空间，打上来源标识、采集日期、操作人，方便后续追溯。
• 对外开放的图片处理接口。调用方传参指定水印文字、位置、透明度、旋转角度，服务端跑一遍后返回处理好的字节流。

这里的“动态”不是指水印会自己动，而是指每次请求时水印的具体内容、样式、位置都能通过参数决定。账号名、价格、时间戳、随机码，这些都是高频动态信息。所以整个设计里最值得花心思的，不是某一个绘制方法，而是一个能承载各种可变参数的处理模型。

1.2 技术选型：标准JDK方案还是第三方图片库

很多同学上来会想用第三方图片处理库，比如 Thumbnailator、imgScalr 甚至 OpenCV。但如果你只需要“下载图片 + 加文字或图片水印 + 输出”，我建议先用 JDK 自带能力，也就是 HttpURLConnection / HttpClient 负责下载，ImageIO 负责解码和编码，Graphics2D 负责绘制。原因很直接：

• JDK 自带方案没有额外依赖，部署环境干净，遇到问题时你能从第一行代码开始排查。
• 水印本质是 2D 绘图，Graphics2D 的能力足够，透明、旋转、抗锯齿、字体控制全都有。
• 这类操作是 CPU 密集型的，第三方库很多时候也只是包装了 BufferedImage 操作，并不能让你省掉真正复杂的边界处理。

什么情况才需要第三方库？当你既要加水印，又要做缩放、裁剪、滤镜、格式转换，或者要处理 WebP、HEIC 这类原生 ImageIO 不支持的格式时，再上重型库不迟。曾经有个图像 Demo 项目用 OpenCV 做水印，结果为了一个纯文本叠加引进来一堆图像处理依赖，编译体积和部署复杂度的性价比很低。

2. 图片下载这一层，远没有想象中简单

2.1 三种HTTP拉取方式对比

下载图片本质就是一个 HTTP GET 请求。Java 里常见有三条路，我直接给一个对比表：

URL.openStream() 我平时只会在本地临时验证时用。它拿不到 HTTP 状态码，万一远端返回一个 403 或者 404 的 HTML 页面，你依然认为自己“下载成功”了，然后 ImageIO 读出来是 null，排查半天才发现问题出现在源头。

2.2 把下载方法写得可靠一点

使用 HttpURLConnection 时，几个关键点要认真处理：连接超时、读取超时、User-Agent、Referer、重定向、响应码校验、单次下载大小限制。我贴一段可以直接落地的代码：

java复制private static final int CONNECT_TIMEOUT = 5000;
private static final int READ_TIMEOUT = 15000;
private static final int MAX_IMAGE_BYTES = 20 * 1024 * 1024;

public static byte[] downloadImage(String imageUrl, String userAgent, String referer) throws IOException {
    HttpURLConnection connection = (HttpURLConnection) new URL(imageUrl).openConnection();
    connection.setConnectTimeout(CONNECT_TIMEOUT);
    connection.setReadTimeout(READ_TIMEOUT);
    connection.setRequestProperty("User-Agent",
        userAgent == null ? "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" : userAgent);
    if (referer != null) {
        connection.setRequestProperty("Referer", referer);
    }
    connection.setInstanceFollowRedirects(true);

    int code = connection.getResponseCode();
    if (code / 100 != 2) {
        connection.disconnect();
        throw new IOException("图片下载失败, HTTP状态码: " + code + ", url: " + imageUrl);
    }

    long contentLength = connection.getContentLengthLong();
    if (contentLength > MAX_IMAGE_BYTES) {
        connection.disconnect();
        throw new IOException("图片超过大小限制: " + contentLength);
    }

    try (InputStream input = connection.getInputStream();
         ByteArrayOutputStream output = new ByteArrayOutputStream(contentLength > 0 ? (int) Math.min(contentLength, 8192) : 8192)) {
        byte[] buffer = new byte[8192];
        int len;
        int total = 0;
        while ((len = input.read(buffer)) != -1) {
            total += len;
            if (total > MAX_IMAGE_BYTES) {
                throw new IOException("下载内容超过 " + MAX_IMAGE_BYTES + " 字节");
            }
            output.write(buffer, 0, len);
        }
        return output.toByteArray();
    } finally {
        connection.disconnect();
    }
}

这里有几个地方值得解释。

第一，为什么要把 contentLength 和实际读取字节数都做限制？因为不是所有图片响应都会带 Content-Length，尤其是传输采用分块编码时，这个值会是 -1。如果只判断头里的长度，恶意地址可以把流量无限拖下去。流式累加判断是更稳的方案。

第二，setInstanceFollowRedirects(true) 是实例级重定向开关，默认其实也是 true，但某些容器环境下全局配置可能影响它，显式设置最保险。如果远端返回 302，而 Location 头又带了一个新的图片地址，这一步能省掉你手写重定向逻辑的功夫。

第三，User-Agent 和 Referer 是防盗链最常见的两道门槛。很多图床看到非浏览器 UA 直接就 403，加了 UA 后成功率会高很多。Referer 则视接口而定，有的接口必须带业务来源。完全不带请求头去拉图，线上一定会遇到莫名其妙失败的情况。

如果你用的是 JDK 11 以上的 HttpClient，代码会简洁很多，很多内部细节都封装得更好：

java复制public static byte[] downloadImageWithHttpClient(String imageUrl, String referer) throws IOException, InterruptedException {
    HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .followRedirects(HttpClient.Redirect.NORMAL)
            .build();

    HttpRequest.Builder builder = HttpRequest.newBuilder(URI.create(imageUrl))
            .timeout(Duration.ofSeconds(15))
            .header("User-Agent", "Mozilla/5.0")
            .GET();
    if (referer != null) {
        builder.header("Referer", referer);
    }

    HttpResponse<byte[]> response = client.send(builder.build(), HttpResponse.BodyHandlers.ofByteArray());
    if (response.statusCode() / 100 != 2) {
        throw new IOException("图片下载失败: " + response.statusCode());
    }
    return response.body();
}

我个人现在新项目都会优先用 HttpClient，但在维护老项目时 HttpURLConnection 那套也很成熟，两者选一个保持统一即可。不要同一个服务里混着用。

2.3 批量下载时的并发与重试

如果业务是一次性处理 1000 张图，那么逐张串行下载速度会很难看。这时候用线程池来处理是常规做法。以固定线程池为例：

java复制int poolSize = Math.max(2, Math.min(Runtime.getRuntime().availableProcessors() * 2, 10));
ExecutorService pool = Executors.newFixedThreadPool(poolSize);

List<CompletableFuture<byte[]>> futures = urlList.stream()
        .map(url -> CompletableFuture.supplyAsync(() -> {
            try {
                return downloadImage(url, null, null);
            } catch (IOException e) {
                throw new RuntimeException(e);
            }
        }, pool))
        .collect(Collectors.toList());

for (CompletableFuture<byte[]> future : futures) {
    byte[] bytes = future.get(30, TimeUnit.SECONDS);
    // 后续解码加水印逻辑
}
pool.shutdown();

批量下载必须做重试。我踩过的坑是：某些图床服务因为限流或瞬时抖动，会随机对部分请求返回 503，单次请求失败率并不低。简单的策略是网络错误或 5xx 错误重试三次，退避间隔可以设成 300ms、800ms、1500ms。4xx 错误一般不要重试，因为可能是参数错误或权限问题，重试只会放大压力。连接超时和读超时要区分开：连接超时可能是对端服务不可达，读超时可能是图片太大或者网络极慢，两者的应对策略不同，日志里要能区分出来。

3. 解码与预处理：从字节到 BufferedImage

3.1 ImageIO 解码的边界

拿到字节数组后，下一步就是用 ImageIO 解码：

java复制BufferedImage image = ImageIO.read(new ByteArrayInputStream(bytes));
if (image == null) {
    throw new IOException("无法识别图片格式，可能不是合法的图片文件");
}

这里有个常见误区：ImageIO.read 返回 null 并不代表没有数据，而是代表它解不了。比如一张 WebP 图片，字节是完好的，但你用原生 API 读出来就是不对劲。ImageIO 原生支持 JPEG、PNG、BMP、GIF、WBMP 这些常见格式，WebP、HEIC、SVG、某些特殊 TIFF 变体都不会原生支持。如果你的业务明确要支持 WebP，就加对应插件，或者提前用图片格式探测能力拦截，否则后续加水印时各种报错会让人摸不着头脑。

另一个值得注意的点是 GIF。ImageIO.read 默认只读动态 GIF 的第一帧，它不会把动图逐帧处理。如果你只做封面水印，这没问题；但如果你以为自己在处理 GIF 动画，那就完全是另一回事了。线条简单的内容平台因为没注意到这一点，出过线上事故，动图素材被处理后只剩静态第一帧。

3.2 图片预处理：透明通道问题必须提前解决

解码出来的 BufferedImage 类型未必适合直接绘制。常见的 BufferedImage 类型有 TYPE_INT_RGB、TYPE_INT_ARGB、索引色等。你要给图片叠加半透明水印，首要前提就是目标图片支持 alpha 合成，否则半透明效果会以很怪异的方式呈现。

一个稳妥的预处理方法是：把需要做水印的图片统一转成 TYPE_INT_ARGB：

java复制public static BufferedImage toArgb(BufferedImage src) {
    if (src.getColorModel().hasAlpha()
            && src.getType() == BufferedImage.TYPE_INT_ARGB) {
        return src;
    }
    BufferedImage target = new BufferedImage(src.getWidth(), src.getHeight(), BufferedImage.TYPE_INT_ARGB);
    Graphics2D g = target.createGraphics();
    g.drawImage(src, 0, 0, null);
    g.dispose();
    return target;
}

但注意，如果你的最终输出格式是 JPEG，那么 TYPE_INT_ARGB 反而是个隐患。JPEG 不支持透明通道，直接把带透明通道的 BufferedImage 写给 JPEG 时，透明区域会变成黑色。我第一次做这个转换时，水印区域周围出现了一团难看的黑色块，排查了很久才意识到是透明背景被 JPEG 编码器“填充”成了黑色。正确做法是先给透明区域填一个底色，再转成 TYPE_INT_RGB：

java复制public static BufferedImage toJpegSafe(BufferedImage src) {
    if (!src.getColorModel().hasAlpha()) {
        return src;
    }
    int w = src.getWidth();
    int h = src.getHeight();
    BufferedImage target = new BufferedImage(w, h, BufferedImage.TYPE_INT_RGB);
    Graphics2D g = target.createGraphics();
    g.setColor(Color.WHITE);
    g.fillRect(0, 0, w, h);
    g.drawImage(src, 0, 0, null);
    g.dispose();
    return target;
}

这段代码的逻辑是：先把白色底色铺满整个画布，再把原图绘制上去。透明区域自然变成白色，水印仍然保留。很多“加完水印图片整体变黑”的线上问题，根因就在这个位置。

4. 动态水印的核心实现

4.1 Graphics2D 绘制水印的基础流程

有了 BufferedImage，接下来就是 Graphics2D 的工作了。一个最基础的带透明度的文字水印绘制流程如下：

java复制public static void drawTextWatermark(BufferedImage image, String text,
        Font font, Color color, float alpha) {
    Graphics2D g2d = image.createGraphics();
    try {
        g2d.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON);
        g2d.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING, RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
        g2d.setRenderingHint(RenderingHints.KEY_RENDERING, RenderingHints.VALUE_RENDER_QUALITY);
        g2d.setComposite(AlphaComposite.getInstance(AlphaComposite.SRC_OVER, alpha));
        g2d.setColor(color);
        g2d.setFont(font);
        g2d.drawString(text, 100, 100);
    } finally {
        g2d.dispose();
    }
}

这里有几个细节新手很容易忽略。

第一，AlphaComposite.getInstance(AlphaComposite.SRC_OVER, alpha) 里的 alpha 是一个 0 到 1 的浮点值，举例来说，0.35 表示水印透明度 35%，隐约但又能看清。如果你在 setColor 里同时设置了带 alpha 的 Color，透明度会发生叠加，这个容易让人困惑，建议只用其中一种方式控制透明度。

第二，RenderingHints 一定要设置。不设置抗锯齿的话，加水印文字边缘会有明显锯齿，尤其是在高清大图缩略后看特别明显。文字抗锯齿和普通几何抗锯齿要分别设置。

第三，dispose() 必须执行。Graphics2D 持有的是本地绘图资源，不释放会造成资源泄漏。把它放到 finally 里是最稳的，不然水印绘制过程抛了异常，资源就一直挂着。

4.2 文字水印的位置计算：baseline 是个大坑

drawString 的坐标 y 并不是文字顶部的 y，而是文字基线的 y。用图形学的话说，字体有 ascent 和 descent，基线以下还有一部分字形空间。如果直接把文字放在期望的左上角坐标上，你会发现文字位置偏高或偏矮。

所以绘制前要用 FontMetrics 量出文字实际尺寸：

java复制FontMetrics fm = g2d.getFontMetrics();
int textWidth = fm.stringWidth(text);
int ascent = fm.getAscent();
int descent = fm.getDescent();
int textHeight = ascent + descent;

常见位置的计算公式可以整理成一张表：

右下角是最常用的位置，因为它对主体图像内容的遮挡最少。完整代码如下：

java复制public static void drawTextWatermark(BufferedImage image, String text,
        WatermarkOptions options, int margin) {
    Graphics2D g2d = image.createGraphics();
    try {
        g2d.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON);
        g2d.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING, RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
        g2d.setComposite(AlphaComposite.getInstance(AlphaComposite.SRC_OVER, options.getAlpha()));
        g2d.setColor(options.getColor());
        g2d.setFont(options.getFont());

        FontMetrics fm = g2d.getFontMetrics();
        int textWidth = fm.stringWidth(text);
        int textHeight = fm.getAscent() + fm.getDescent();
        int x = image.getWidth() - textWidth - margin;
        int y = image.getHeight() - fm.getDescent() - margin;

        AffineTransform old = g2d.getTransform();
        if (options.getRotateDegree() != 0) {
            g2d.rotate(Math.toRadians(options.getRotateDegree()), x, y);
        }
        g2d.drawString(text, x, y);
        g2d.setTransform(old);
    } finally {
        g2d.dispose();
    }
}

如果只做垂直方向的旋转，比如水印文字倾斜 45 度，可以用 g2d.rotate。注意绕哪个点旋转很重要。我的做法是围绕文字左下角旋转，也就是 (x, y) 这个点，这样旋转后的文字不会飘出预期区域太远。如果你希望水印围绕图片中心旋转，那就要换成图片的中心坐标。

旋转前要保存 AffineTransform，绘制完成后再恢复，不然会污染后续绘制上下文。这个看似微小的细节，在实际项目里坑过我很长时间：水印旋转之后，后面画图或写别的文字时位置全部错位。

4.3 图片Logo水印的叠加

动态水印不一定只有文字，很多平台还要叠一个平台 Logo 或者小图标。图片水印实现更简单，核心就是 drawImage：

java复制public static void drawImageWatermark(BufferedImage image, BufferedImage logo,
        int offsetX, int offsetY, float alpha) {
    Graphics2D g2d = image.createGraphics();
    try {
        g2d.setComposite(AlphaComposite.getInstance(AlphaComposite.SRC_OVER, alpha));
        int x = image.getWidth() - logo.getWidth() - offsetX;
        int y = image.getHeight() - logo.getHeight() - offsetY;
        g2d.drawImage(logo, x, y, null);
    } finally {
        g2d.dispose();
    }
}

这里有个容易忽略的点：BufferedImage 解码后的图片如果本身有透明通道，drawImage 时透明部分也会跟着绘制过去。比如你的 Logo 是 PNG 格式，四周留白是透明的，直接画上去没问题；但如果你的 Logo 本身是白底的 JPEG，那就会看到一块白色矩形压在图片上，非常丑。稳妥做法是先把 Logo 转成带 alpha 的 TYPE_INT_ARGB，再绘制。

另外，不要试图直接在这个方法里给 Logo 做缩放。缩放需要额外的插值设置，如果你不设置 RenderingHints.KEY_INTERPOLATION，缩出来的 Logo 边缘会非常粗糙。给 Logo 加水印前先单独处理，不要在每次绘制时临时计算。

4.4 平铺水印怎么做才自然

有些场景要求防截图的力度更大，光在角落放一个水印不够，需要把水印平铺在整个图片上。平铺的难点在于旋转和平铺要同时生效，处理不好就会乱。

我的做法是：先旋转整个画布，再编码一个覆盖全图的循环网格。因为画布旋转后原图边界会超出原本的视觉范围，所以循环范围要适当放大：

java复制public static void drawTiledTextWatermark(BufferedImage image, String text,
        Font font, Color color, float alpha, double rotateDegree, int gap) {
    Graphics2D g2d = image.createGraphics();
    try {
        g2d.setRenderingHint(RenderingHints.KEY_ANTIALIASING, RenderingHints.VALUE_ANTIALIAS_ON);
        g2d.setRenderingHint(RenderingHints.KEY_TEXT_ANTIALIASING, RenderingHints.VALUE_TEXT_ANTIALIAS_ON);
        g2d.setComposite(AlphaComposite.getInstance(AlphaComposite.SRC_OVER, alpha));
        g2d.setColor(color);
        g2d.setFont(font);

        FontMetrics fm = g2d.getFontMetrics();
        int textWidth = fm.stringWidth(text);
        int cellX = textWidth + gap;
        int cellY = fm.getHeight() + gap;

        AffineTransform old = g2d.getTransform();
        g2d.rotate(Math.toRadians(rotateDegree), image.getWidth() / 2.0, image.getHeight() / 2.0);

        int startX = -image.getWidth();
        int startY = -image.getHeight();
        for (int y = startY; y < image.getHeight() * 2; y += cellY) {
            for (int x = startX; x < image.getWidth() * 2; x += cellX) {
                g2d.drawString(text, x, y);
            }
        }

        g2d.setTransform(old);
    } finally {
        g2d.dispose();
    }
}

为什么循环起点要用负的原图宽高值，终点用两倍宽高？因为旋转后原先图片角落区域的文字会被转出去，如果循环范围还是 0 到原图宽高，旋转后的四个角必然出现空白。这种略微超量的方案换来的是全图无死角的覆盖，适合要求严格防截图的业务。gap 参数控制水印之间的疏密，我一般取文字高度的一倍到两倍，视觉效果比较均匀，又不至于太刺眼。

4.5 给白色背景图片加水印的小技巧

纯白背景、浅色背景的图片是文字水印的“天敌”。白色半透明水印在白色背景上几乎看不清，黑色半透明水印又容易盖住图像内容。多个内容平台最终采用的方案是“描边水印”：先用深色把文字往右下偏移 1 到 2 个像素绘制一遍，形成阴影，再在左上绘制白色文字。这样无论图片亮部还是暗部，水印都能保持可读性。

实现上其实就是上面 drawTextWatermark 方法调用两次，第一次偏移坐标并设置深色，第二次使用正常坐标和浅色。阴影的 alpha 可以比主文字低一些，避免太重。

5. 输出、内存与工程化打磨

5.1 输出格式：JPG质量和PNG透明兼容

处理完的 BufferedImage 最终要写回字节流。ImageIO.write 是最简单的出口，但 JPEG 质量它没有给你暴露参数，默认压缩质量有时候不太理想。控制 JPEG 质量要用 ImageWriter 和 ImageWriteParam：

java复制public static void writeJpeg(BufferedImage image, OutputStream out, float quality) throws IOException {
    ImageWriter writer = ImageIO.getImageWritersByFormatName("jpeg").next();
    try (ImageOutputStream ios = ImageIO.createImageOutputStream(out)) {
        ImageWriteParam param = writer.getDefaultWriteParam();
        param.setCompressionMode(ImageWriteParam.MODE_EXPLICIT);
        param.setCompressionQuality(quality);
        writer.setOutput(ios);
        writer.write(null, new IIOImage(image, null, null), param);
    } finally {
        writer.dispose();
    }
}

quality 取值 0 到 1，0.85 是我常用的值，输出体积和视觉质量比较均衡。如果是对清晰度非常敏感的图片，可以调到 0.92 以上，但体积会明显变大。PNG 输出则直接用 ImageIO.write(image, "png", out)，前提是 image 已经转成了 TYPE_INT_ARGB，否则 PNG 里的半透明效果会失真。

这里有个我踩过的温知识：JPEG 编码器对部分图像有明显的色差问题，尤其是红色和蓝色渐变区域。加了水印后，水印区域有可能出现色块。解决方案不是放弃水印，而是保证水印层的 alpha 不要过高。alpha 在 0.3 到 0.5 之间视觉效果会比较自然，超过 0.7 之后叠加边缘容易产生肉眼可见的过渡色。

5.2 内存占用和并发安全的工程细节

图片处理是内存敏感型操作。一张 5000×4000 的 TYPE_INT_ARGB 图片，占用内存大约 5000×4000×4 字节，也就是 80MB，这还没算解码时的中间缓冲区和下载时的字节数组。如果批量处理，很容易出现 OOM。

我总结出的几条实用约束：

• 单张解码前，先读图片宽高，超尺寸的直接拒绝或做降采样处理。
• 批量下载时限制积压任务数量，用信号量或固定线程池把并发控制在一定范围内。
• 处理完一张图后立刻把字节数组置为可回收状态，不要在一个 List 里囤积所有处理结果。
• Graphics2D 和 BufferedImage 都不是线程安全的。多线程并发处理时，每个线程独占自己的图片对象，绝不能共享同一个 Graphics2D 实例。

读取图片尺寸而不直接解码，可以用 ImageReader：

java复制public static int[] readImageSize(byte[] bytes) throws IOException {
    try (ImageInputStream iis = ImageIO.createImageInputStream(new ByteArrayInputStream(bytes))) {
        Iterator<ImageReader> readers = ImageIO.getImageReaders(iis);
        if (!readers.hasNext()) {
            return null;
        }
        ImageReader reader = readers.next();
        try {
            reader.setInput(iis);
            int width = reader.getWidth(0);
            int height = reader.getHeight(0);
            return new int[]{width, height};
        } finally {
            reader.dispose();
        }
    }
}

这个方法只读头信息，不会把整个像素矩阵加载进内存，比直接 ImageIO.read 再判断尺寸要省得多。

5.3 设计一个可扩展的水印处理入口

动态水印要做到“参数可配置”，最好把所有变化的东西收敛到一个配置对象里。我推荐定义一个简单的参数类：

java复制public class WatermarkSpec {
    private String text;
    private BufferedImage logo;
    private WatermarkPosition position = WatermarkPosition.RIGHT_BOTTOM;
    private float alpha = 0.35f;
    private float rotateDegree;
    private int fontSize = 28;
    private String fontName = Font.SANS_SERIF;
    private Color color = Color.WHITE;
    private String outputFormat = "jpg";
    private float jpegQuality = 0.85f;
    // getter/setter
}

对应一个只对外暴露最简单接口的服务：

java复制public byte[] process(String imageUrl, WatermarkSpec spec) throws Exception {
    byte[] sourceBytes = downloadImage(imageUrl, spec.getUserAgent(), spec.getReferer());
    BufferedImage source = decode(sourceBytes);

    if ("png".equalsIgnoreCase(spec.getOutputFormat())) {
        source = toArgb(source);
    } else {
        source = toJpegSafe(source);
    }

    if (spec.getText() != null && !spec.getText().isEmpty()) {
        drawTextWatermark(source, spec.getText(), spec, getSpecFont(spec));
    }
    if (spec.getLogo() != null) {
        drawImageWatermark(source, spec.getLogo(), 16, 16, spec.getAlpha());
    }

    ByteArrayOutputStream output = new ByteArrayOutputStream();
    if ("png".equalsIgnoreCase(spec.getOutputFormat())) {
        ImageIO.write(source, "png", output);
    } else {
        writeJpeg(source, output, spec.getJpegQuality());
    }
    return output.toByteArray();
}

这个结构的好处是，业务侧的调用基本只有一个方法，水印文字、位置、透明度、旋转、格式全部由入参决定。后续要增加“按用户等级显示不同水印”“按时间切换水印批次”之类的功能，都是在 WatermarkSpec 上扩展，不会把下载、解码、绘制这三级逻辑打乱。我在项目里按类似结构做过一次重构，后面加随机平铺水印只花了不到半小时，因为大部分代码都已经拆得很干净了。

6. 高频问题与排查经验

6.1 线上踩坑速查表

下面是我做图片水印服务过程中实际遇到过的典型问题，按现象、根因、处理方式整理成表：

6.2 几个值得长期坚持的习惯

先说异常设计。下载错误、解码失败、水印绘制异常这三类错误要分开记日志。只记一个笼统的“图片处理失败”，上线后排查等于大海捞针。我曾经因为日志里没有记录是“下载超时”还是“解码失败”，在一个批量任务里反复踩同一个坑。后来加了分类异常和对应 URL 的上下文信息，一次定位就解决。

再说图片大小限制。对外提供的图片下载接口，如果完全没有大小上限，攻击者可以丢给你一个超大图片，把你的内存打满。我的原则是：能用 Content-Length 判断的先判断，判断不了的就靠读取时累计字节数，双重保险。

最后一个建议：水印处理写完之后，要用不同格式的测试图回归一遍。至少覆盖带透明通道的 PNG、白底 JPEG、彩色 JPEG、中文文字水印、数字水印、长图片、宽图片这七种情况。很多问题不是代码写错，而是没有覆盖到图片本身的多样性。我见过一个项目只拿一张测试图调通了，上线后被用户传的各种奇怪图片瞬间打爆。

这个功能做到后面，真正的复杂度不在水印绘制本身，而在前端的下载稳定性、中间的格式兼容、后端的内存控制这些“外围工程”。你把超时、防盗链、透明通道、字体、内存、批量并发都补全了，才能说这是一个能在生产环境站稳脚跟的图片水印服务。希望这份笔记能帮你在自己的项目里少走一段弯路。