C# 时间戳与日期转换工具类源码分享

在日常开发中，时间戳与 DateTime的相互转换是非常高频的操作。不同的系统接口可能采用秒级、毫秒级时间戳或各种字符串格式。为了统一管理这些转换逻辑，我封装了一个简单实用的工具类，支持 Unix 秒/毫秒时间戳、ISO8601 字符串以及自定义格式的互转，并自动适配时区。

以下是完整的实现源码与使用示例，可直接用于项目中。

🔧 工具类源码

using System;
using System.Globalization;

namespace TimeUtils
{
    /// <summary>
    /// 时间戳与日期转换工具类
    /// </summary>
    public static class DateTimeHelper
    {
        private static readonly DateTime _unixEpoch = 
            new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc);

        // 本地时区与 UTC 的偏移（适用于中国时区）
        private static readonly TimeSpan _chinaOffset = 
            TimeZoneInfo.Local.GetUtcOffset(DateTime.Now);

        /// <summary>
        /// 将 DateTime 转为 Unix 秒级时间戳
        /// </summary>
        public static long ToUnixTimeSeconds(DateTime dateTime)
        {
            if (dateTime.Kind == DateTimeKind.Unspecified)
                dateTime = DateTime.SpecifyKind(dateTime, DateTimeKind.Local);
            
            var utcTime = dateTime.ToUniversalTime();
            return (long)(utcTime - _unixEpoch).TotalSeconds;
        }

        /// <summary>
        /// 将 DateTime 转为 Unix 毫秒级时间戳
        /// </summary>
        public static long ToUnixTimeMilliseconds(DateTime dateTime)
        {
            if (dateTime.Kind == DateTimeKind.Unspecified)
                dateTime = DateTime.SpecifyKind(dateTime, DateTimeKind.Local);
            
            var utcTime = dateTime.ToUniversalTime();
            return (long)(utcTime - _unixEpoch).TotalMilliseconds;
        }

        /// <summary>
        /// 将 Unix 秒级时间戳转为 DateTime（本地时间）
        /// </summary>
        public static DateTime FromUnixTimeSeconds(long seconds)
        {
            var utcTime = _unixEpoch.AddSeconds(seconds);
            return TimeZoneInfo.ConvertTimeFromUtc(utcTime, TimeZoneInfo.Local);
        }

        /// <summary>
        /// 将 Unix 毫秒级时间戳转为 DateTime（本地时间）
        /// </summary>
        public static DateTime FromUnixTimeMilliseconds(long milliseconds)
        {
            var utcTime = _unixEpoch.AddMilliseconds(milliseconds);
            return TimeZoneInfo.ConvertTimeFromUtc(utcTime, TimeZoneInfo.Local);
        }

        /// <summary>
        /// 将日期转为 ISO8601 格式字符串（yyyy-MM-ddTHH:mm:ssZ）
        /// </summary>
        public static string ToIso8601String(DateTime dateTime)
        {
            return dateTime.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ");
        }

        /// <summary>
        /// 将 ISO8601 格式字符串转为 DateTime
        /// </summary>
        public static DateTime FromIso8601String(string isoString)
        {
            return DateTime.ParseExact(
                isoString,
                "yyyy-MM-ddTHH:mm:ssZ",
                CultureInfo.InvariantCulture,
                DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal
            ).ToLocalTime();
        }

        /// <summary>
        /// 按指定格式字符串转为 DateTime
        /// </summary>
        public static DateTime ParseByFormat(string dateStr, string format)
        {
            return DateTime.ParseExact(
                dateStr,
                format,
                CultureInfo.CurrentCulture,
                DateTimeStyles.None
            );
        }

        /// <summary>
        /// 获取当前时间的秒级时间戳
        /// </summary>
        public static long CurrentUnixSeconds => ToUnixTimeSeconds(DateTime.Now);

        /// <summary>
        /// 获取当前时间的毫秒级时间戳
        /// </summary>
        public static long CurrentUnixMilliseconds => ToUnixTimeMilliseconds(DateTime.Now);
    }
}

📝 使用示例

class Program
{
    static void Main()
    {
        var now = DateTime.Now;

        // 1. 转秒级/毫秒级时间戳
        long seconds = DateTimeHelper.ToUnixTimeSeconds(now);
        long ms = DateTimeHelper.ToUnixTimeMilliseconds(now);
        Console.WriteLine($"秒级: {seconds}, 毫秒级: {ms}");

        // 2. 时间戳转回日期
        DateTime dt1 = DateTimeHelper.FromUnixTimeSeconds(seconds);
        DateTime dt2 = DateTimeHelper.FromUnixTimeMilliseconds(ms);
        Console.WriteLine($"还原后: {dt1:yyyy-MM-dd HH:mm:ss}");
        
        // 3. ISO8601 序列化
        string iso = DateTimeHelper.ToIso8601String(now);
        Console.WriteLine($"ISO8601: {iso}");
        
        DateTime dt3 = DateTimeHelper.FromIso8601String(iso);
        Console.WriteLine($"解析后: {dt3:yyyy-MM-dd HH:mm:ss}");

        // 4. 自定义格式
        string customFmt = "2025-03-20 14:30";
        DateTime dt4 = DateTimeHelper.ParseByFormat(customFmt, "yyyy-MM-dd HH:mm");
        Console.WriteLine($"自定义解析: {dt4:G}");

        // 5. 快速获取当前时间戳
        Console.WriteLine($"当前秒级: {DateTimeHelper.CurrentUnixSeconds}");
    }
}

输出结果示例：

秒级: 1744691234, 毫秒级: 1744691234567
还原后: 2025-04-15 10:07:14
ISO8601: 2025-04-15T02:07:14Z
解析后: 2025-04-15 10:07:14
自定义解析: 2025/3/20 14:30:00
当前秒级: 1744691568

⚙️ 设计要点说明

时区一致性：
- 内部统一基于 UTC 时间计算 Unix 时间戳，通过 ToUniversalTime()和 TimeZoneInfo.ConvertTimeFromUtc确保在不同时区服务器上行为一致。
未指定 Kind 的处理：
- 当传入的 DateTime为 Unspecified时，默认视为本地时间再进行 UTC 转换，减少歧义。
扩展性：
- 提供了常用格式（Unix 秒/毫秒、ISO8601）的快捷方法，同时保留 ParseByFormat供自定义格式扩展。
线程安全：
- 静态工具类，无状态，所有方法均为纯函数，可在多线程环境中安全调用。

🛠 适用场景

API 接口中时间字段序列化为时间戳或标准字符串；
日志文件名或目录按日期+时间戳命名；
跨平台/跨语言数据交换中的时间表示（优先推荐 ISO8601）；
定时任务、缓存过期时间的时间计算。

此工具类不依赖第三方库，兼容 .NET Framework 4.5+ / .NET Core / .NET 5+，开箱即用。如果在 Linux 容器或不同时区环境运行，会自动适配本地时区偏移，无需额外配置。

🔧 工具类源码

📝 使用示例

⚙️ 设计要点说明

🛠 适用场景

相关文章