timezone

package
v0.17.10 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 1, 2026 License: MIT Imports: 3 Imported by: 0

README

Timezone 组件

「数据库存 UTC、前端展示北京时间」约定下的通用时区工具,提供时间格式化与解析能力,并通过 Formatter 支持调用方注入业务专属的时间字段集合,避免全局可变状态。

概述

多个中国区项目共用同一约定:时间以 UTC 写入数据库,对外展示时转换为北京时间(Asia/Shanghai)。Timezone 组件封装该约定下的全套操作:

  • 约定统一:写库用 NowUTCString,展示用 *ToShanghai / FormatShanghai,全项目一套口径
  • 解析容错:优先按 UTC 解析,失败时回退服务器本地时区,兼容历史遗留的本地时间数据
  • 无全局可变状态:时间字段集合由 Formatter 实例持有,按实例隔离,多业务线互不干扰
  • 零依赖降级:系统缺失 tzdata 时自动回退为固定东八区偏移,行为不变

功能特性

常量与变量
  • DateTimeFormat:标准格式 2006-01-02 15:04:05
  • Shanghai:北京时间时区,time.LoadLocation 失败时回退 time.FixedZone("Asia/Shanghai", 8*3600)
写库(UTC)
  • NowUTCString():当前 UTC 时间字符串,直接写入数据库时间字段
展示(北京时间)
  • UTCStringToShanghai(s):UTC 字符串转北京时间字符串;空值或解析失败原样返回
  • FormatShanghai(t):time.Time 格式化为北京时间字符串;零值返回空字符串
  • Formatter.ToShanghaiString(s) / Formatter.FormatShanghai(t):同上,时区可实例级覆盖
解析
  • ParseUTCString(s):按内置 layout 列表依次尝试,全部失败返回错误
  • 内置 layout 覆盖 RFC3339(含 Nano)、标准日期时间(含毫秒/微秒)、2006-01-02 等常见格式
Formatter(实例级配置)
  • 时间字段集合:AddTimeFields / IsTimeField,判定某字段是否需时区格式化
  • 时区覆盖:Location 字段,未设置时回退 Shanghai
  • 解析 layout 覆盖:ParseLayouts 字段,未设置时用内置默认值
  • FormatValue(val):统一处理 time.Time 或时间字符串,供响应序列化的 FormatTime 回调注入

安装指南

依赖要求
  • Go 1.26.0+
安装依赖

组件已包含在 jcbaseGo 模块中,无需额外安装:

go get github.com/jcbowen/jcbaseGo

使用示例

写库与展示的基本流
package main

import (
    "fmt"

    "github.com/jcbowen/jcbaseGo/component/timezone"
)

func main() {
    // 写库:UTC 字符串
    utcStr := timezone.NowUTCString()
    fmt.Println(utcStr) // 例如: 2026-10-21 00:30:00(UTC)

    // 展示:转北京时间
    fmt.Println(timezone.UTCStringToShanghai(utcStr)) // 例如: 2026-10-21 08:30:00

    // time.Time 直接格式化
    fmt.Println(timezone.FormatShanghai(time.Now())) // 例如: 2026-10-21 08:30:00
}
解析时间字符串
t, err := timezone.ParseUTCString("2026-10-21 08:30:00")
if err != nil {
    // 所有 layout 均解析失败
    return
}
// 解析结果按 UTC 语义使用;对历史本地时间数据会自动回退本地时区解析
Formatter:注入业务时间字段
formatter := timezone.NewFormatter("created_at", "updated_at", "pay_time")

// 判定字段是否走时区格式化
if formatter.IsTimeField("created_at") {
    // ...
}

// 单个值处理:time.Time 或字符串均可
if s, ok := formatter.FormatValue("2026-10-21 00:30:00"); ok {
    fmt.Println(s) // 2026-10-21 08:30:00
}
与 serializer 组件联动

Formatter.FormatValue 可直接作为 serializer.Options.FormatTime 注入,实现响应数据的时间字段统一转北京时间:

import (
    "github.com/jcbowen/jcbaseGo/component/serializer"
    "github.com/jcbowen/jcbaseGo/component/timezone"
)

formatter := timezone.NewFormatter("created_at", "updated_at")

data := serializer.Process(respData,
    serializer.WithTimeField(formatter.IsTimeField),
    serializer.WithFormatTime(formatter.FormatValue),
)

详细功能说明

解析优先级

ParseUTCString 与 Formatter.parseString 均采用两轮策略:

  1. 第一轮:所有 layout 按 UTC 解析(符合 UTC 存库约定)
  2. 第二轮:所有 layout 按 服务器本地时区 解析(兼容历史遗留本地时间数据)
零值与空值语义
输入 处理
空字符串 原样返回空串
0000-00-00 00:00:00 FormatValue 视为无效,返回空串且 ok=false
time.Time 零值 返回空串
解析失败的字符串 原样返回(不覆盖非标准字段)
Formatter 的隔离性

每个 Formatter 实例独立持有时间字段集合,AddTimeFields 只影响当前实例。不同业务线(如订单、IM)可各自创建 Formatter,避免全局注册表带来的耦合。

API 参考

包级函数
  • NowUTCString() string - 当前 UTC 时间字符串(写库用)
  • UTCStringToShanghai(s string) string - UTC 字符串转北京时间;空/解析失败原样返回
  • FormatShanghai(t time.Time) string - time.Time 格式化为北京时间;零值返回空串
  • ParseUTCString(s string) (time.Time, error) - 解析时间字符串,优先 UTC 后本地时区
Formatter
  • NewFormatter(extraFields ...string) *Formatter - 创建格式化器,可追加业务时间字段
  • AddTimeFields(keys ...string) - 追加时间字段名(仅当前实例)
  • IsTimeField(key string) bool - 判断字段是否需时区格式化
  • ToShanghaiString(s string) string - UTC 字符串转当前实例时区字符串
  • FormatShanghai(t time.Time) string - time.Time 格式化为当前实例时区字符串
  • FormatValue(val interface{}) (string, bool) - 统一处理 time.Time/字符串,返回 (北京时间字符串, 是否成功)
可配置字段
type Formatter struct {
    Location     *time.Location // 时区,未设置回退 Shanghai
    ParseLayouts []string       // 解析 layout,未设置用内置默认值
    // timeFields 为私有字段,经 AddTimeFields / IsTimeField 操作
}

常见问题

为什么展示时间比库里时间多 8 小时?

库中存的是 UTC,展示按约定转北京时间(UTC+8),这是预期行为。若前端直接展示库中原始值出现偏差,检查是否漏走了 ToShanghaiString / FormatValue。

历史数据是本地时间怎么办?

解析函数第一轮按 UTC、第二轮按本地时区,新旧数据都能正确解析;展示侧统一输出北京时间,用户无感知。

容器里没有 tzdata 会影响吗?

不会。Shanghai 初始化失败时自动回退为固定东八区偏移(time.FixedZone),格式化与解析行为一致。

贡献指南

欢迎提交 Issue 和 Pull Request 来改进这个组件。

许可证

MIT License

Documentation

Overview

Package timezone 提供"数据库存 UTC、前端展示北京时间"约定的通用时区工具。

多个中国区项目共用同一约定:时间以 UTC 写入数据库,对外展示时转换为 北京时间(Asia/Shanghai)。本包封装该约定下的格式化与解析能力, 并通过 Formatter 支持调用方注入业务专属的时间字段集合,避免全局可变状态。

Index

Constants

View Source
const DateTimeFormat = "2006-01-02 15:04:05"

DateTimeFormat 标准日期时间格式

Variables

View Source
var Shanghai *time.Location

Shanghai 北京时间时区。系统缺失 tzdata 时回退为固定东八区偏移。

Functions

func FormatShanghai

func FormatShanghai(t time.Time) string

FormatShanghai 将 time.Time(按 UTC 解析)格式化为北京时间字符串。

参数:

  • t: 时间值

返回值:

  • string: 北京时间字符串;零值返回空字符串

func NowUTCString

func NowUTCString() string

NowUTCString 返回当前 UTC 时间的标准字符串表示,用于写入数据库的时间字段。

返回值:

  • string: UTC 时间字符串,格式为 2006-01-02 15:04:05

func ParseUTCString

func ParseUTCString(s string) (time.Time, error)

ParseUTCString 将时间字符串解析为 time.Time。 优先按 UTC 解析,失败时回退到服务器本地时区,兼容历史本地时间数据。

参数:

  • s: 时间字符串

返回值:

  • time.Time: 解析后的时间
  • error: 所有 layout 均解析失败时返回错误

func UTCStringToShanghai

func UTCStringToShanghai(s string) string

UTCStringToShanghai 将 UTC 时间字符串转换为北京时间字符串。 输入为空或解析失败时原样返回,避免覆盖非标准字段。

参数:

  • s: UTC 时间字符串

返回值:

  • string: 北京时间字符串;解析失败时返回原值

Types

type Formatter

type Formatter struct {
	Location     *time.Location
	ParseLayouts []string
	// contains filtered or unexported fields
}

Formatter 时区格式化器。时间字段集合与解析 layout 由调用方注入,避免全局可变状态。

func NewFormatter

func NewFormatter(extraFields ...string) *Formatter

NewFormatter 创建 Formatter;extraFields 为业务追加的时间字段名。

func (*Formatter) AddTimeFields

func (f *Formatter) AddTimeFields(keys ...string)

AddTimeFields 向当前 Formatter 追加时间字段名(仅修改当前实例,不影响其他实例)。

func (*Formatter) FormatShanghai

func (f *Formatter) FormatShanghai(t time.Time) string

FormatShanghai 将 time.Time 格式化为北京时间字符串;零值返回空字符串。

func (*Formatter) FormatValue

func (f *Formatter) FormatValue(val interface{}) (string, bool)

FormatValue 处理单个时间值(time.Time 或时间字符串),统一转换为北京时间字符串。 供响应中间件的 Options.FormatTime 注入使用。

参数:

  • val: 原始字段值,支持 time.Time 或时间字符串

返回值:

  • string: 格式化后的北京时间字符串
  • bool: 是否成功识别并格式化

func (*Formatter) IsTimeField

func (f *Formatter) IsTimeField(key string) bool

IsTimeField 判断字段名是否需做时区格式化。

func (*Formatter) ToShanghaiString

func (f *Formatter) ToShanghaiString(s string) string

ToShanghaiString 将 UTC 时间字符串转为北京时间字符串;空/解析失败原样返回。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL