Go에서 HTTP 파일 업로드를 구현하는 방법｜net/http・multipart・S3 대응

Go의 표준 라이브러리 net/http과 mime/multipart를 사용하면 외부 패키지 없이 파일 업로드를 구현할 수 있습니다. 본 글에서는 r.ParseMultipartForm()을 통한 멀티파트 본문 파싱, r.FormFile()을 통한 파일 획득, 파일 크기 제한, MIME 타입 검증에서 AWS SDK v2를 사용한 S3 업로드까지 실무 수준의 구현을 상세히 설명합니다.

net/http에서의 멀티파트 요청 수신

multipart/form-data 요청을 받으려면 r.ParseMultipartForm(maxMemory)를 호출합니다. maxMemory는 메모리에 보관할 최대 바이트 수이며, 초과분은 임시 파일에 쓰입니다.

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"path/filepath"
	"time"
)

func uploadHandler(w http.ResponseWriter, r *http.Request) {
	if r.Method != http.MethodPost {
		http.Error(w, "Method Not Allowed", http.StatusMethodNotAllowed)
		return
	}

	// 最大10MBをメモリに保持し、超過分は /tmp に一時保存
	const maxMemory = 10 << 20 // 10MB
	if err := r.ParseMultipartForm(maxMemory); err != nil {
		http.Error(w, "フォームの解析に失敗しました: "+err.Error(), http.StatusBadRequest)
		return
	}

	// フォームの文字列フィールドを取得
	title := r.FormValue("title")
	fmt.Printf("title: %s\n", title)

	// ファイルを取得
	file, header, err := r.FormFile("file")
	if err != nil {
		http.Error(w, "ファイルの取得に失敗しました: "+err.Error(), http.StatusBadRequest)
		return
	}
	defer file.Close()

	fmt.Printf("ファイル名: %s\n", header.Filename)
	fmt.Printf("ファイルサイズ: %d bytes\n", header.Size)
	fmt.Printf("Content-Type: %s\n", header.Header.Get("Content-Type"))

	// 保存先のパスを生成
	timestamp := time.Now().UnixNano()
	safeFilename := filepath.Base(header.Filename) // ディレクトリトラバーサル対策
	destPath := fmt.Sprintf("./uploads/%d_%s", timestamp, safeFilename)

	// ファイルを保存
	dst, err := os.Create(destPath)
	if err != nil {
		http.Error(w, "ファイルの作成に失敗しました", http.StatusInternalServerError)
		return
	}
	defer dst.Close()

	if _, err := io.Copy(dst, file); err != nil {
		http.Error(w, "ファイルの書き込みに失敗しました", http.StatusInternalServerError)
		return
	}

	w.Header().Set("Content-Type", "application/json")
	fmt.Fprintf(w, `{"success":true,"filename":%q}`, safeFilename)
}

func main() {
	os.MkdirAll("./uploads", 0755)
	http.HandleFunc("/upload", uploadHandler)
	log.Println("サーバー起動: :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

파일 크기 제한 구현

http.MaxBytesReader를 사용하면 요청 본문의 읽기량을 제한할 수 있습니다. ParseMultipartForm의 인수만으로는 요청 전체 크기를 제한할 수 없으므로, MaxBytesReader와의 조합이 중요합니다.

package handler

import (
	"errors"
	"net/http"
)

const (
	MaxUploadSize = 50 << 20 // 50MB
	MaxMemory     = 10 << 20 // 10MB（メモリに保持する最大量）
)

func uploadHandler(w http.ResponseWriter, r *http.Request) {
	// リクエストボディ全体のサイズを制限
	r.Body = http.MaxBytesReader(w, r.Body, MaxUploadSize)

	if err := r.ParseMultipartForm(MaxMemory); err != nil {
		var maxBytesErr *http.MaxBytesError
		if errors.As(err, &maxBytesErr) {
			http.Error(w, fmt.Sprintf("ファイルサイズが上限（%dMB）を超えています。", MaxUploadSize>>20), http.StatusRequestEntityTooLarge)
		} else {
			http.Error(w, "不正なリクエストです。", http.StatusBadRequest)
		}
		return
	}

	file, header, err := r.FormFile("file")
	if err != nil {
		http.Error(w, "ファイルの取得に失敗しました。", http.StatusBadRequest)
		return
	}
	defer file.Close()

	// ヘッダーのサイズも確認（ParseMultipartForm 後でも確認可能）
	if header.Size > MaxUploadSize {
		http.Error(w, "ファイルが大きすぎます。", http.StatusRequestEntityTooLarge)
		return
	}

	// ... 以降の処理
}

MIME 타입 검증

클라이언트가 신고한 Content-Type 헤더는 위조될 수 있습니다. 실제 파일 내용의 선행 바이트(매직 넘버)를 읽고 http.DetectContentType으로 판정하는 것이 안전합니다.

package handler

import (
	"fmt"
	"mime/multipart"
	"net/http"
)

var allowedMIMETypes = map[string]bool{
	"image/jpeg":      true,
	"image/png":       true,
	"image/gif":       true,
	"image/webp":      true,
	"application/pdf": true,
	"application/zip": true,
}

// detectMIMEType はファイルの先頭512バイトを読んでMIMEタイプを判定します
func detectMIMEType(file multipart.File) (string, error) {
	// 先頭512バイトを読む（http.DetectContentType は最大512バイトを使用）
	buf := make([]byte, 512)
	n, err := file.Read(buf)
	if err != nil && err.Error() != "EOF" {
		return "", fmt.Errorf("ファイルの読み込みに失敗しました: %w", err)
	}

	// ファイルポインタを先頭に戻す（後続の読み込みのため）
	if seeker, ok := file.(interface{ Seek(int64, int) (int64, error) }); ok {
		if _, err := seeker.Seek(0, 0); err != nil {
			return "", fmt.Errorf("シークに失敗しました: %w", err)
		}
	}

	mimeType := http.DetectContentType(buf[:n])
	return mimeType, nil
}

func validateFile(file multipart.File, header *multipart.FileHeader) error {
	// 実際のMIMEタイプを検出
	mimeType, err := detectMIMEType(file)
	if err != nil {
		return err
	}

	if !allowedMIMETypes[mimeType] {
		return fmt.Errorf("許可されていないファイル形式です（%s）", mimeType)
	}

	return nil
}

AWS SDK v2를 사용한 S3 업로드

Go의 AWS SDK v2는 SDK v1보다 크게 개선되었으며, 컨텍스트 지원과 모듈 분할이 특징입니다. 멀티파트 업로드는 s3manager.Upload가 자동으로 처리합니다.

go get github.com/aws/aws-sdk-go-v2/config
go get github.com/aws/aws-sdk-go-v2/service/s3
go get github.com/aws/aws-sdk-go-v2/feature/s3/manager

package s3upload

import (
	"context"
	"fmt"
	"io"
	"mime/multipart"
	"os"
	"time"

	"github.com/aws/aws-sdk-go-v2/aws"
	"github.com/aws/aws-sdk-go-v2/config"
	"github.com/aws/aws-sdk-go-v2/feature/s3/manager"
	"github.com/aws/aws-sdk-go-v2/service/s3"
)

type S3Uploader struct {
	uploader *manager.Uploader
	bucket   string
}

func NewS3Uploader(ctx context.Context) (*S3Uploader, error) {
	// 環境変数（AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION）から設定を読み込む
	cfg, err := config.LoadDefaultConfig(ctx,
		config.WithRegion(os.Getenv("AWS_REGION")),
	)
	if err != nil {
		return nil, fmt.Errorf("AWS 設定の読み込みに失敗しました: %w", err)
	}

	client := s3.NewFromConfig(cfg)
	uploader := manager.NewUploader(client, func(u *manager.Uploader) {
		u.PartSize = 10 * 1024 * 1024 // 10MB パートサイズ
		u.Concurrency = 3             // 並列アップロード数
	})

	return &S3Uploader{
		uploader: uploader,
		bucket:   os.Getenv("AWS_S3_BUCKET"),
	}, nil
}

func (u *S3Uploader) Upload(ctx context.Context, file io.Reader, header *multipart.FileHeader, mimeType string) (string, error) {
	// ユニークなキーを生成
	timestamp := time.Now().UnixNano()
	key := fmt.Sprintf("uploads/%d_%s", timestamp, header.Filename)

	result, err := u.uploader.Upload(ctx, &s3.PutObjectInput{
		Bucket:      aws.String(u.bucket),
		Key:         aws.String(key),
		Body:        file,
		ContentType: aws.String(mimeType),
		// ACL を使わずバケットポリシーで制御する場合は省略
	})
	if err != nil {
		return "", fmt.Errorf("S3 へのアップロードに失敗しました: %w", err)
	}

	return result.Location, nil
}

// Presigned URL の生成（プライベートファイルへの一時アクセス）
func GeneratePresignedURL(ctx context.Context, bucket, key string, expiry time.Duration) (string, error) {
	cfg, err := config.LoadDefaultConfig(ctx)
	if err != nil {
		return "", err
	}

	client := s3.NewFromConfig(cfg)
	presigner := s3.NewPresignClient(client)

	req, err := presigner.PresignGetObject(ctx, &s3.GetObjectInput{
		Bucket: aws.String(bucket),
		Key:    aws.String(key),
	}, s3.WithPresignExpires(expiry))
	if err != nil {
		return "", fmt.Errorf("Presigned URL の生成に失敗しました: %w", err)
	}

	return req.URL, nil
}

Echo 프레임워크에서의 구현 예제

웹 프레임워크 Echo를 사용하면 라우팅과 미들웨어를 간단하게 구성할 수 있습니다. 파일 업로드 처리는 표준 net/http와 동일한 메커니즘입니다.

package main

import (
	"net/http"

	"github.com/labstack/echo/v4"
	"github.com/labstack/echo/v4/middleware"
)

func main() {
	e := echo.New()
	e.Use(middleware.Logger())
	e.Use(middleware.Recover())

	e.POST("/upload", func(c echo.Context) error {
		// マルチパートフォームを解析（最大32MBまでメモリに保持）
		if err := c.Request().ParseMultipartForm(32 << 20); err != nil {
			return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
		}

		file, err := c.FormFile("file")
		if err != nil {
			return c.JSON(http.StatusBadRequest, map[string]string{"error": "ファイルが見つかりません"})
		}

		src, err := file.Open()
		if err != nil {
			return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
		}
		defer src.Close()

		// MIMEタイプの検証
		mimeType, err := detectMIMEType(src)
		if err != nil || !allowedMIMETypes[mimeType] {
			return c.JSON(http.StatusUnsupportedMediaType, map[string]string{
				"error": "許可されていないファイル形式です",
			})
		}

		return c.JSON(http.StatusOK, map[string]interface{}{
			"filename": file.Filename,
			"size":     file.Size,
			"mime":     mimeType,
		})
	})

	e.Logger.Fatal(e.Start(":8080"))
}

❓ 자주 묻는 질문

Go에서 외부 패키지 없이 파일 업로드를 구현할 수 있나요?

예. Go 표준 라이브러리 net/http와 mime/multipart만으로 파일 업로드를 완전히 구현할 수 있습니다. r.ParseMultipartForm()으로 멀티파트 본문을 해석하고 r.FormFile()로 파일을 가져옵니다. 외부 패키지가 필요한 것은 S3 등 클라우드 스토리지에 업로드할 때뿐입니다.

Go에서 MIME 타입을 안전하게 검증하려면?

http.DetectContentType() 함수를 사용합니다. 이 함수는 파일 선두 최대 512바이트를 읽어 매직 넘버로 MIME 타입을 판정합니다. 클라이언트가 신고하는 Content-Type 헤더는 조작할 수 있으므로 보조 참고 정보로만 쓰고 실제 파일 내용으로 검증하는 것이 중요합니다.

Go의 AWS SDK v1과 v2의 차이는?

AWS SDK v2는 v1보다 모듈이 세분화되어 필요한 서비스 패키지만 임포트할 수 있습니다. context.Context 지원이 표준화되고 인터페이스가 정리되었으며 성능도 개선되었습니다. 신규 프로젝트에서는 v2 사용이 권장되며, go get github.com/aws/aws-sdk-go-v2/service/s3 처럼 개별적으로 임포트합니다.