io.CopyN 限制上传读取长度的处理方案

在 Go 的 HTTP 文件上传里，io.CopyN 适合把“本次最多读取多少字节”落到代码中，但它不是完整的超限拒绝器。最稳妥的做法是把读取上限设为“业务上限加 1 字节”：先允许最多多读一个字节，再根据 written 判断请求是否超过上限，只有未超限时才把临时文件提交成正式文件。

我在处理分块传输上传时最容易踩的坑，是把 io.CopyN(dst, src, limit) 的 nil 错误理解成“请求体没有超过 limit”。实际上，它只保证本次复制拿到了 limit 字节；请求后面是否还有内容，它没有替你确认。下面按一次上传处理链路，把限制对象、返回值和文件提交边界拆开。

先分清 CopyN 限制的到底是什么

io.CopyN 的签名是 CopyN(dst Writer, src Reader, n int64)。它的语义是从 src 向 dst 复制最多需要的 n 字节，返回已经写入的数量和错误。官方实现等价于围绕 io.LimitReader(src, n) 做复制：当写入数正好等于 n 时返回成功；源数据提前结束时，返回的错误通常是 io.EOF。

因此，io.CopyN(file, r.Body, maxBytes) 能保证这次复制不会主动超过 maxBytes，但它不能仅凭一次成功返回证明整个请求体恰好只有这么大。对于上传场景，我们通常还需要回答另一个问题：写入到上限后，输入是否还有第一个额外字节？

把请求体放进可控的读取边界

HTTP 请求的 Content-Length 可能没有值，分块传输时还可能是 -1，所以不能只依赖请求头判断大小。可以先用 Content-Length 做快速拒绝，再用 http.MaxBytesReader 包住请求体，最后让 io.CopyN 只取上限加一字节。

“加一字节”是这里的关键：读取 limit+1 字节时，如果得到第一个额外字节，就能确定上传超限；如果只得到不超过 limit 的内容并以 io.EOF 结束，则说明请求体没有超过业务上限。这样既不需要把整个请求读入内存，也不会为了判断超限而无限读取。

package upload

import (
    "errors"
    "io"
    "net/http"
    "os"
)

const maxUploadBytes int64 = 10  maxUploadBytes {
        return "", errors.New("upload exceeds size limit")
    }

    // 多保留一个字节用于识别“刚好达到上限”和“已经超限”。
    r.Body = http.MaxBytesReader(w, r.Body, maxUploadBytes+1)
    defer r.Body.Close()

    temp, err := os.CreateTemp("", "upload-*.part")
    if err != nil {
        return "", err
    }
    tempName := temp.Name()
    committed := false
    defer func() {
        // 任何错误或提前返回都清理半成品，成功重命名后不再删除。
        _ = temp.Close()
        if !committed {
            _ = os.Remove(tempName)
        }
    }()

    written, copyErr := io.CopyN(temp, r.Body, maxUploadBytes+1)
    if written > maxUploadBytes {
        return "", errors.New("upload exceeds size limit")
    }
    if copyErr != nil && !errors.Is(copyErr, io.EOF) {
        return "", copyErr
    }
    if err := temp.Close(); err != nil {
        return "", err
    }

    finalName := tempName + ".ready"
    if err := os.Rename(tempName, finalName); err != nil {
        return "", err
    }
    committed = true
    return finalName, nil
}

这段代码把“写入临时文件”和“成为正式文件”分成两个状态。注意 io.EOF 在这里不一定是失败：它只表示请求体在读完上限加一字节之前结束，若 written 没超过上限，短文件是否允许由业务决定。真正的读取异常则不能被吞掉。

用 written 和 err 区分四类结果

判断上传结果时不要只看 err == nil，也不要把所有 io.EOF 都当成错误。更有用的判断顺序是先看是否读到了额外字节，再看错误是否为 io.EOF，最后处理其他错误。

func classifyCopyResult(written int64, copyErr error, limit int64) error {
    // 读到上限之外的第一个字节，优先判定为超限。
    if written > limit {
        return errors.New("upload exceeds size limit")
    }

    // EOF 只表示输入提前结束；是否允许小于上限的文件由业务规则决定。
    if errors.Is(copyErr, io.EOF) {
        return nil
    }

    // 其他错误代表底层读取或写入链路异常，不能提交半成品。
    return copyErr
}

对于“必须达到某个最小长度”的业务，还要在 written 上补充最小值判断；io.CopyN 只负责复制边界，不会替你解释文件是否完整、格式是否正确或是否已经通过业务校验。

先写临时文件，再在成功分支提交

如果直接把目标文件作为 dst，超限请求可能已经写入了上限加一字节，底层错误也可能留下无法使用的半成品。把目标路径和临时路径分开，可以把“可被发现的正式文件”作为最后一步动作：复制、判断、关闭都成功后，再通过重命名提交。

这里还有三个容易遗漏的资源边界：

• 请求体：无论复制成功还是失败，都要关闭 r.Body，由当前处理函数承担的关闭责任要明确。
• 临时文件：错误路径要删除；成功重命名后，延迟清理不能再把正式文件误删。
• 关闭错误：文件关闭失败也应视为提交失败，不能只看 io.CopyN 的返回值。

Content-Length 只是快路径，不是完整方案

请求头中的 Content-Length 大于上限时，可以直接返回 413 Request Entity Too Large，减少一次临时文件创建。但它缺失、未知或不可信时，仍然要依靠 MaxBytesReader 和“上限加一字节”的读取策略。换句话说，头部判断是节省工作的快路径，读取边界才是最终保护。

func uploadHandler(w http.ResponseWriter, r *http.Request) {
    // 已知长度超限时尽早结束，避免无意义地创建临时文件。
    if r.ContentLength > maxUploadBytes {
        http.Error(w, "request entity too large", http.StatusRequestEntityTooLarge)
        return
    }

    path, err := copyUpload(w, r)
    if err != nil {
        // 这里可以按错误类型映射 413 或 400，不能把所有错误都返回 500。
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    // 只有临时文件已提交，才向调用方返回成功。
    w.WriteHeader(http.StatusCreated)
    _, _ = w.Write([]byte(path))
}

落地时的速查表

结论：CopyN 负责复制边界，业务代码负责超限语义

io.CopyN 很适合限制一次复制最多读取多少字节，但上传是否超限、短文件是否允许、文件何时算正式提交，都需要业务代码补齐。对 HTTP 上传而言，实用组合是：Content-Length 做快路径，MaxBytesReader 做请求体保护，CopyN(limit+1) 识别额外字节，最后用临时文件和重命名控制提交边界。

相关问题

为什么不直接把 CopyN 的 n 设成上传上限？

这样只能复制到上限，无法知道输入后面是否还有内容；读取上限加一字节后，才能用 written > limit 判定超限。

小于上限时的 io.EOF 要不要报错？

不一定。它表示源在达到本次复制目标前结束；如果业务允许任意不超过上限的文件，可以接受，否则再增加最小长度或格式检查。

MaxBytesReader 能替代 io.CopyN 吗？

它们关注点不同：MaxBytesReader 限制从请求体读取的总量，io.CopyN 限制当前复制操作的目标量。上传落盘时可以组合使用，前者保护请求边界，后者控制复制语义。