1: 开始使用 Carbon
1.1 简介
一个简单、语义化且对开发者友好的 Golang 日期时间处理包
使用 Carbon 进行日期时间处理的好处：
- 对开发者友好：Carbon 提供了一个流畅且富有表现力的接口来处理日期时间，直观易懂。
- 国际化支持：支持国际化，允许你本地化日期表示。
- 不可变性：Carbon 实例是不可变的，意味着可以安全地传递而不会发生意外修改。
- 时区处理：Carbon 简化了跨不同时区管理日期时间的复杂性。
- 广泛的 API：提供了一整套用于创建、解析和格式化日期和时间的函数。
1.2 安装指南
针对 Go 版本 >= 1.16 的安装
要为 Go 版本 1.16 或以上安装 Carbon 包，请使用以下命令：
go get -u github.com/golang-module/carbon/v2
然后，在你的 Go 文件中导入该包：
import "github.com/golang-module/carbon/v2"
针对 Go 版本 < 1.16 的安装
对于旧版本的 Go，你仍然可以使用以下命令安装 Carbon：
go get -u github.com/golang-module/carbon
并以类似方式导入它：
import "github.com/golang-module/carbon"
请注意，v1 不再积极更新，但会维护以修复 bug。
1.3 设置您的首个 Carbon 项目
Carbon 的基本配置： 安装完 Carbon 后，你可以通过简单地创建一个新的 Carbon 实例来开始使用它。 你可以通过设置默认的全局布局、时区和语言环境来自定义 Carbon，以适应你项目的需求。
设置全局默认布局、时区和语言环境：
carbon.SetDefault(carbon.Default{
Layout: carbon.RFC3339Layout,
Timezone: carbon.PRC,
Locale: "en",
})
如果没有显式设置，Carbon 有这些默认设置 —— Layout: "2006-01-02 15:04:05"、Timezone: Local、Locale: "en"。
2: 基本的 Carbon 操作
2.1 处理当前时间
获取当前日期和时间
在许多应用程序中，检索当前日期和时间是一个基本操作。通过 Carbon，您可以通过调用 carbon.Now() 方法获取当前的日期时间实例。让我们看看如何获取当前日期时间：
// 获取当前日期和时间作为 Carbon 实例。
now := carbon.Now()
fmt.Println("当前日期时间:", now)
显示今天、昨天和明天
Carbon 提供了一种优雅的方式来处理相对于当前日期的日期。要获取今天、昨天和明天的日期时间表示，分别可以使用 carbon.Now()、carbon.Yesterday() 和 carbon.Tomorrow() 方法：
// 今天的日期时间
today := carbon.Now()
fmt.Println("今天:", today.ToDateTimeString())
// 昨天的日期时间
yesterday := carbon.Yesterday()
fmt.Println("昨天:", yesterday.ToDateTimeString())
// 明天的日期时间
tomorrow := carbon.Tomorrow()
fmt.Println("明天:", tomorrow.ToDateTimeString())
这些方法提供了一种简洁的方式来与这些常用的日期引用进行交互，而无需手动计算。
格式化和表示当前时间
Carbon 提供了不同的方式来格式化和显示日期时间。无论您需要标准格式（如 ISO8601）、自定义格式或本地化版本，Carbon 都有适合这些需求的方法。
以下是您可以以各种方式格式化当前日期时间的示例：
// 标准日期时间表示
fmt.Println("RFC3339:", now.ToRFC3339String())
fmt.Println("ISO8601:", now.ToIso8601String())
// 自定义日期时间格式
fmt.Println("自定义:", now.Format("Monday, 02-Jan-06 15:04:05 MST"))
// 使用预定义的布局
fmt.Println("ANSIC 格式:", now.ToAnsicString())
fmt.Println("UnixDate 格式:", now.ToUnixDateString())
fmt.Println("RubyDate 格式:", now.ToRubyDateString())
fmt.Println("Kitchen 格式:", now.ToKitchenString())
// 对于自定义模式，请使用 Format 方法
fmt.Println("自定义模式:", now.Format("2006-01-02 3:04 PM"))
从时间戳创建实例
在 Go 中，处理时间戳很频繁，Carbon 提供了直观的方法来处理它们。时间戳是标识特定事件发生时间的一系列字符或编码信息，通常提供日期和时间，并且有时准确到秒的小部分。
要从 Unix 时间戳创建一个 Carbon 实例，Unix 时间戳表示自 Unix 纪元（1970 年 1 月 1 日协调世界时午夜）以来经过的秒数，你可以使用不同的精度级别：
// 使用秒精度从给定的时间戳创建 Carbon 实例
c1 := carbon.CreateFromTimestamp(1596604455)
fmt.Println(c1.ToString()) // 输出: "202-08-05 13:14:15 +080 CST"
// 对于更高精度（毫秒），使用 `CreateFromTimestampMilli`
c2 := carbon.CreateFromTimestampMilli(1596604455999)
fmt.Println(c2.ToString()) // 输出: "202-08-05 13:14:15.999 +080 CST"
// 对于微秒，使用 `CreateFromTimestampMicro`
c3 := carbon.CreateFromTimestampMicro(1596604455999999)
fmt.Println(c3.ToString()) // 输出: "202-08-05 13:14:15.999999 +080 CST"
// 对于纳秒，使用 `CreateFromTimestampNano`
c4 := carbon.CreateFromTimestampNano(1596604455999999999)
fmt.Println(c4.ToString()) // 输出: "202-08-05 13:14:15.999999999 +080 CST"
从日期和时间组件创建实例
如果你有日期的各个组成部分，例如年、月和日，或时间的组成部分，比如小时、分钟和秒，Carbon 也可以处理这些。
// 仅使用给定日期创建 Carbon 实例
date := carbon.CreateFromDate(2022, 12, 25)
fmt.Println(date.ToDateString()) // 输出: "2022-12-25"
// 仅使用给定时间创建 Carbon 实例
time := carbon.CreateFromTime(23, 59, 59)
fmt.Println(time.ToTimeString()) // 输出: "23:59:59"
// 从日期和时间创建 Carbon 实例
dateTime := carbon.CreateFromDateTime(2022, 12, 25, 23, 59, 59)
fmt.Println(dateTime.ToDateTimeString()) // 输出: "2022-12-25 23:59:59"
2.3 解析时间字符串
将日期时间表示为字符串是常见的情况。Carbon 使得将字符串解析为 Carbon 实例非常方便。
使用 carbon.Parse 处理标准时间格式：
// 解析带有日期和时间的字符串
c := carbon.Parse("202-08-05 13:14:15", carbon.PRC)
if c.Error != nil {
fmt.Printf("错误: %v", c.Error)
} else {
fmt.Println(c.ToDateTimeString()) // 输出: "202-08-05 13:14:15"
}
// 解析 RFC3339 格式的字符串
rfc3339 := carbon.Parse("202-08-05T13:14:15+08:00")
fmt.Println(rfc3339.ToString()) // 输出: "202-08-05 13:14:15 +080 CST"
使用 ParseByFormat 和 ParseByLayout 自定义格式：
你也可以解析特定格式的字符串，这些格式无法直接被 carbon.Parse 处理。
// 按照格式将时间字符串解析成 Carbon 实例
byFormat := carbon.ParseByFormat("202|08|05 13|14|15", "2006|01|02 15|04|05")
fmt.Println(byFormat.ToDateTimeString()) // 输出: "202-08-05 13:14:15"
// 按照布局将时间字符串解析成 Carbon 实例
byLayout := carbon.ParseByLayout("202|08|05", "2006|01|02")
fmt.Println(byLayout.ToDateString()) // 输出: "202-08-05"
处理错误
始终检查 Error 字段以确保解析成功：
invalidDate := carbon.Parse("This is not a date", carbon.PRC)
if invalidDate.IsInvalid() {
fmt.Println("解析日期出错:", invalidDate.Error)
}
记住，进行健壮的错误检查是处理日期和时间的关键部分，以防止意外结果或系统崩溃。