Go语言时间戳类型详解与使用方法

本文深入解析了Go语言中自定义Timestamp类型的安全实现方案，聚焦于解决JSON序列化与MongoDB BSON交互中的常见痛点——尤其是因方法接收者类型不一致（如值接收者内非法取地址）导致的编译错误；通过统一采用指针接收者、增强nil/零值防护、兼容数字与字符串双格式JSON时间戳、适配新版MongoDB驱动（go.mongodb.org/mongo-driver/bson）及提供开箱即用的构造函数（Now、New、Unix），构建出生产就绪、语义清晰且高度可复用的时间戳封装，助你轻松实现高效、安全、跨生态兼容的时间处理逻辑。

本文详解如何在Go中安全实现支持JSON序列化、MongoDB BSON交互的自定义Timestamp类型，重点解决方法接收者不匹配导致的编译错误，并提供可直接复用的构造函数与最佳实践。

本文详解如何在Go中安全实现支持JSON序列化、MongoDB BSON交互的自定义Timestamp类型，重点解决方法接收者不匹配导致的编译错误，并提供可直接复用的构造函数与最佳实践。

在Go开发中，为结构体字段统一使用Unix时间戳（int64）格式进行JSON序列化，同时保留time.Time的语义和BSON兼容性，是常见需求。但直接基于type Timestamp time.Time定义并实现json.Marshaler/bson.Getter等接口时，极易因方法接收者类型不一致引发编译错误——如原文中的 invalid indirect of t (type Timestamp)，其根本原因在于：GetBSON 和 SetBSON 方法声明为值接收者（func (t Timestamp) GetBSON()），却在方法体内对 t 进行取地址操作（如 &t 或 *t），而值类型的变量不可寻址。

✅ 正确实现：统一使用指针接收者

为确保所有方法均可安全读写底层time.Time值，所有自定义方法均应采用指针接收者（*Timestamp）。以下是修复后的完整、生产就绪版本（已适配现代Go生态，弃用已归档的 labix.org/v2/mgo，改用官方 go.mongodb.org/mongo-driver/bson）：

package timestamp

import (
    "fmt"
    "strconv"
    "time"

    "go.mongodb.org/mongo-driver/bson"
    "go.mongodb.org/mongo-driver/bson/primitive"
)

// Timestamp 是 time.Time 的别名，用于定制JSON/BSON序列化行为
type Timestamp time.Time

// MarshalJSON 将时间序列化为Unix时间戳整数（字符串形式，如 "1717023456"）
func (t *Timestamp) MarshalJSON() ([]byte, error) {
    if t == nil || time.Time(*t).IsZero() {
        return []byte("null"), nil
    }
    ts := time.Time(*t).Unix()
    return []byte(fmt.Sprintf("%d", ts)), nil
}

// UnmarshalJSON 从Unix时间戳整数（字符串或数字）反序列化
func (t *Timestamp) UnmarshalJSON(b []byte) error {
    if len(b) == 0 || string(b) == "null" {
        *t = Timestamp(time.Time{})
        return nil
    }

    // 兼容 JSON 数字（如 1717023456）和字符串（如 "1717023456"）
    var tsInt int64
    var err error

    if b[0] == '"' { // 字符串格式
        var s string
        if err = json.Unmarshal(b, &s); err != nil {
            return err
        }
        tsInt, err = strconv.ParseInt(s, 10, 64)
    } else { // 原生数字格式
        if err = json.Unmarshal(b, &tsInt); err != nil {
            return err
        }
    }
    if err != nil {
        return fmt.Errorf("invalid timestamp format: %s", string(b))
    }

    *t = Timestamp(time.Unix(tsInt, 0))
    return nil
}

// GetBSON 实现 bson.Marshaler 接口：转换为标准 time.Time 供MongoDB驱动使用
func (t *Timestamp) GetBSON() (interface{}, error) {
    if t == nil || time.Time(*t).IsZero() {
        return nil, nil
    }
    return time.Time(*t), nil
}

// SetBSON 实现 bson.Unmarshaler 接口：从BSON time.Time或primitive.DateTime解析
func (t *Timestamp) SetBSON(raw bson.Raw) error {
    var tm time.Time
    if err := raw.Unmarshal(&tm); err == nil {
        *t = Timestamp(tm)
        return nil
    }

    // 兼容 MongoDB 的 primitive.DateTime (int64 毫秒时间戳)
    var dt primitive.DateTime
    if err := raw.Unmarshal(&dt); err == nil {
        *t = Timestamp(time.Unix(int64(dt)/1000, int64(dt)%1000*1000000))
        return nil
    }

    return fmt.Errorf("cannot unmarshal BSON into Timestamp")
}

// String 返回标准 time.Time 字符串表示，便于日志和调试
func (t *Timestamp) String() string {
    if t == nil {
        return ""
    }
    return time.Time(*t).String()
}

// --- 实用构造函数（推荐使用）---

// New 创建指定时间的 Timestamp 指针
func New(t time.Time) *Timestamp {
    return &Timestamp(t)
}

// Now 创建当前时间的 Timestamp 指针
func Now() *Timestamp {
    return New(time.Now())
}

// Unix 创建指定Unix秒时间戳的 Timestamp 指针
func Unix(sec int64) *Timestamp {
    return New(time.Unix(sec, 0))
}

⚠️ 关键修正说明：

• GetBSON 和 SetBSON 均改为 *Timestamp 接收者，避免编译错误；
• MarshalJSON/UnmarshalJSON 增加 nil 和零值安全检查；
• UnmarshalJSON 支持 JSON 数字与字符串双格式；
• SetBSON 兼容 time.Time 和 primitive.DateTime，适配新版MongoDB驱动。

✅ 正确使用方式：构造与赋值

在结构体中声明字段时，*务必使用指针类型 `timestamp.Timestamp`**，并在初始化时通过构造函数创建实例：

package main

import (
    "fmt"
    "your-module/timestamp" // 替换为实际路径
)

type User struct {
    Name      string              `bson:"name" json:"name"`
    CreatedAt *timestamp.Timestamp `bson:"created_at,omitempty" json:"created_at,omitempty"`
}

func main() {
    // ✅ 正确：使用构造函数
    u1 := User{
        Name:      "Alice",
        CreatedAt: timestamp.Now(), // 推荐：简洁、安全、可读性强
    }

    // ✅ 正确：显式构造
    now := time.Now()
    u2 := User{
        Name:      "Bob",
        CreatedAt: timestamp.New(now),
    }

    // ✅ 正确：从Unix时间戳创建
    u3 := User{
        Name:      "Charlie",
        CreatedAt: timestamp.Unix(1717023456),
    }

    // ❌ 错误：不能直接类型转换（Timestamp不是time.Time的别名指针）
    // u := User{CreatedAt: (*timestamp.Timestamp)(time.Now())} // 编译失败

    fmt.Printf("User: %+v\n", u1)
}

? 总结与最佳实践

• 接收者一致性：所有修改状态的方法（包括GetBSON/SetBSON）必须使用指针接收者 *Timestamp；
• 零值与nil安全：在MarshalJSON/UnmarshalJSON/GetBSON中显式处理 nil 和 time.Time{}，避免panic；
• 优先使用构造函数：timestamp.Now()、timestamp.New(t) 比手动类型转换更安全、语义更清晰；
• 依赖更新：使用 go.mongodb.org/mongo-driver/bson 替代已废弃的 mgo，确保长期维护性；
• 测试覆盖：务必为JSON序列化/反序列化、BSON编解码编写单元测试，验证边界情况（如空值、非法字符串）。

遵循以上规范，即可在微服务、API后端或MongoDB应用中稳健地集成自定义时间戳类型，兼顾序列化效率、数据库兼容性与代码可维护性。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Go语言时间戳类型详解与使用方法》文章吧，也可关注golang学习网公众号了解相关技术文章。