星河避难所

一次被封 IP 之后：从 Shadowsocks 到 Xray Reality

Mon, 09 Mar 2026 07:17:12 GMT

⚠️ 本文仅为个人技术研究记录，用于学习网络协议与服务器部署，请遵守当地法律法规。

我之前一直用的是 Shadowsocks，配置简单、部署也很轻量。一台服务器开个端口基本就能跑起来，用了很长一段时间都没什么问题。

原本的文章链接在这里，密码是一样的：点击前往

直到有一天，我发现它突然连不上了。

服务器本身是正常的，SSH 也能登录，国外访问也没问题，但国内连接就是不通。简单排查了一圈之后，基本可以确定是 IP 被封 了。

这种情况其实挺常见的，尤其是长期使用单一协议的时候。

幸好云服务器可以通过弹性IP去切换IP，于是我干脆把这次当成一个契机，重新研究了一下现在主流的一些方案，最后选择了基于 Xray 的 VLESS + Reality 组合。

这篇文章就简单记录一下整个折腾过程。

安装 Xray

官方提供了一个非常方便的安装脚本，仓库在这里：https://github.com/XTLS/Xray-install

只需要执行脚本里的 install-release.sh 就可以完成安装。

bash install-release.sh

安装完成之后，一般会生成两个主要文件：

/usr/local/bin/xray
/usr/local/etc/xray/config.json

其中：

/usr/local/bin/xray 是程序本体
/usr/local/etc/xray/config.json 是默认配置文件

后续我们主要就是修改这个配置文件。

生成 UUID

在使用 VLESS 的时候，需要一个 UUID 作为客户端身份标识。

最简单的方式是直接在服务器上生成：

cat /proc/sys/kernel/random/uuid

输出类似这样：c9a1e0f2-xxxx-xxxx-xxxx-xxxxxxxxxxxx

只要是标准 UUID 格式就可以，用在线工具生成其实也没问题。

这个 UUID 后面会写进配置文件里，同时客户端也需要使用同一个值。

生成密钥对

Reality 需要使用一对 X25519 密钥。

可以直接用 Xray 自带的命令生成：

xray x25519

会得到类似这样的输出：

PrivateKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
PublicKey:  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Hash32:     xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

其中：

PrivateKey：服务端使用
PublicKey：客户端使用
Hash32：用于校验

简单理解就是：

服务端持有私钥
客户端使用公钥进行连接

完善配置文件

接下来需要修改 Xray 的配置文件：/usr/local/etc/xray/config.json

在编写配置之前，需要确保服务器端口是开放的，没有被防火墙拦截。可以通过下面的方式简单检查：

nc -vz 服务器IP 端口号

如果端口是通的，一般会看到类似：Connection to xxx.xxx.xxx.xxx port xxxx [tcp/*] succeeded!

配置文件本身其实就是一份 JSON 结构，大致包含几个部分：

inbounds：客户端入口
outbounds：流量出口
routing：路由规则
realitySettings：Reality 相关配置

个人自用的完整配置模板如下：

{
  'log': { 'loglevel': 'debug' },
  'inbounds':
    [
      {
        'port': 服务器端口,
        'protocol': 'vless',
        'settings':
          {
            'clients': [{ 'id': '生成的UUID', 'flow': 'xtls-rprx-vision' }],
            'decryption': 'none',
            'fallbacks': [{ 'dest': 80 }]
          },
        'streamSettings':
          {
            'network': 'tcp',
            'security': 'reality',
            'realitySettings':
              {
                'show': false,
                'dest': 'www.cloudflare.com:443',
                'xver': 0,
                'serverNames': ['www.cloudflare.com'],
                'privateKey': '生成密钥对中的PrivateKey',
                'shortIds':
                  [
                    '0-16位字母或数字',
                    '自定义标识,类似密码,可以设置多个',
                    '客户端携带的信息与任意一个匹配则通过'
                  ]
              }
          },
        'sniffing': { 'enabled': true, 'destOverride': ['http', 'tls'] }
      }
    ],
  'outbounds': [{ 'protocol': 'freedom' }]
}

启动 Xray

配置完成之后，就可以通过 systemd 管理 Xray 服务了。

常用命令如下：

启动服务：

systemctl start xray

重启服务：

systemctl restart xray

查看状态：

systemctl status xray

查看实时日志：

journalctl -u xray -f

设置开机自启：

systemctl enable xray

如果配置有问题，日志里通常会直接报错，定位问题其实还算方便。

通过 Clash 连接

客户端我使用的是 Clash。

PC端我会选择 Clash Verge 「GitHub」「官方网站」

移动端我会选择 FlClash 「GitHub」

Clash 的配置文件本质上是一个 YAML 文件，其中最核心的部分其实是 规则（rules） 。

规则的基本格式是：匹配类型, 匹配内容, 处理方式

例如：DOMAIN-SUFFIX,google.com,Proxy

意思是：所有以 google.com 结尾的域名，都通过 Proxy 这个代理组处理。

常见处理方式

规则匹配之后，需要决定如何处理流量。

常见的处理方式包括：

REJECT: 拒绝访问。
BLOCK: 同样是拒绝访问。
DIRECT: 直接访问目标服务器，不经过代理。
代理组名称: 如果填写的是代理组名称，例如：Proxy，就表示流量会交给 proxy-groups 中定义的名为 Proxy 的代理组处理。

常见匹配类型

DOMAIN

完全匹配域名

DOMAIN,google.com,Proxy

只有 google.com 会匹配。

DOMAIN-SUFFIX

后缀匹配

DOMAIN-SUFFIX,google.com,Proxy

例如：

www.google.com
mail.google.com

都会匹配。

DOMAIN-KEYWORD

关键字匹配

DOMAIN-KEYWORD,google,Proxy

只要域名里包含 google 都会匹配，比如：

google.com
googleapis.com

IP-CIDR

IP 段匹配

IP-CIDR,8.8.8.8/32,Proxy

这里 /32 表示精确匹配单个 IP。

GEOIP

按国家 IP 匹配

GEOIP,CN,DIRECT

表示中国大陆 IP 直接连接，不走代理。

MATCH

默认规则

MATCH,Proxy

如果前面的规则都没有匹配，就使用这个。

示例配置

下面是我个人使用的一份配置结构示例（隐去了服务器信息）：

port: 7890
socks-port: 7891
redir-port: 7892
allow-lan: false
mode: Rule
log-level: info
external-controller: 127.0.0.1:9090
secret: ''
cfw-bypass:
  - localhost
  - 127.*
  - 10.*
  - 172.16.*
  - 172.17.*
  - 172.18.*
  - 172.19.*
  - 172.20.*
  - 172.21.*
  - 172.22.*
  - 172.23.*
  - 172.24.*
  - 172.25.*
  - 172.26.*
  - 172.27.*
  - 172.28.*
  - 172.29.*
  - 172.30.*
  - 172.31.*
  - 192.168.*
  - <local>
cfw-latency-timeout: 3000
proxies:
  - name: 名称，我喜欢写我的服务器IP
    type: vless
    server: 我的服务器IP
    port: 服务端配置的端口
    uuid: 服务端配置的uuid
    network: tcp
    tls: true
    udp: false
    flow: xtls-rprx-vision
    servername: www.cloudflare.com
    client-fingerprint: chrome
    reality-opts:
      public-key: 服务端配置私钥对应的公钥
      short-id: 服务端配置的shortIds
proxy-groups:
  - name: 代理组名称
    type: select
    proxies:
      - proxies配置的名称
rules:
  - DOMAIN,hls.itunes.apple.com,代理组名称
  - DOMAIN,itunes.apple.com,代理组名称
  - DOMAIN,itunes.com,代理组名称
  - DOMAIN-SUFFIX,icloud.com,DIRECT
  - DOMAIN-SUFFIX,icloud-content.com,DIRECT
  - DOMAIN-SUFFIX,me.com,DIRECT
  - DOMAIN-SUFFIX,mzstatic.com,DIRECT
  - DOMAIN-SUFFIX,aaplimg.com,DIRECT
  - DOMAIN-SUFFIX,cdn-apple.com,DIRECT
  - DOMAIN-SUFFIX,apple.com,DIRECT
  ## 国内网站
  - DOMAIN-SUFFIX,akadns.net,DIRECT
  - DOMAIN-SUFFIX,akamaized.net,DIRECT
  - DOMAIN-SUFFIX,cn,DIRECT
  - DOMAIN-KEYWORD,-cn,DIRECT
  - DOMAIN-SUFFIX,126.com,DIRECT
  - DOMAIN-SUFFIX,126.net,DIRECT
  - DOMAIN-SUFFIX,127.net,DIRECT
  - DOMAIN-SUFFIX,163.com,DIRECT
  - DOMAIN-SUFFIX,360buyimg.com,DIRECT
  - DOMAIN-SUFFIX,36kr.com,DIRECT
  - DOMAIN-SUFFIX,acfun.tv,DIRECT
  - DOMAIN-SUFFIX,air-matters.com,DIRECT
  - DOMAIN-SUFFIX,aixifan.com,DIRECT
  - DOMAIN-KEYWORD,alicdn,DIRECT
  - DOMAIN-KEYWORD,alipay,DIRECT
  - DOMAIN-KEYWORD,taobao,DIRECT
  - DOMAIN-SUFFIX,amap.com,DIRECT
  - DOMAIN-SUFFIX,autonavi.com,DIRECT
  - DOMAIN-KEYWORD,baidu,DIRECT
  - DOMAIN-SUFFIX,bdimg.com,DIRECT
  - DOMAIN-SUFFIX,bdstatic.com,DIRECT
  - DOMAIN-SUFFIX,bilibili.com,DIRECT
  - DOMAIN-SUFFIX,caiyunapp.com,DIRECT
  - DOMAIN-SUFFIX,clouddn.com,DIRECT
  - DOMAIN-SUFFIX,cnbeta.com,DIRECT
  - DOMAIN-SUFFIX,cnbetacdn.com,DIRECT
  - DOMAIN-SUFFIX,cootekservice.com,DIRECT
  - DOMAIN-SUFFIX,csdn.net,DIRECT
  - DOMAIN-SUFFIX,ctrip.com,DIRECT
  - DOMAIN-SUFFIX,dgtle.com,DIRECT
  - DOMAIN-SUFFIX,dianping.com,DIRECT
  - DOMAIN-SUFFIX,douban.com,DIRECT
  - DOMAIN-SUFFIX,doubanio.com,DIRECT
  - DOMAIN-SUFFIX,duokan.com,DIRECT
  - DOMAIN-SUFFIX,easou.com,DIRECT
  - DOMAIN-SUFFIX,ele.me,DIRECT
  - DOMAIN-SUFFIX,feng.com,DIRECT
  - DOMAIN-SUFFIX,fir.im,DIRECT
  - DOMAIN-SUFFIX,frdic.com,DIRECT
  - DOMAIN-SUFFIX,g-cores.com,DIRECT
  - DOMAIN-SUFFIX,godic.net,DIRECT
  - DOMAIN-SUFFIX,gtimg.com,DIRECT
  - DOMAIN-SUFFIX,hongxiu.com,DIRECT
  - DOMAIN-SUFFIX,hxcdn.net,DIRECT
  - DOMAIN-SUFFIX,iciba.com,DIRECT
  - DOMAIN-SUFFIX,ifeng.com,DIRECT
  - DOMAIN-SUFFIX,ifengimg.com,DIRECT
  - DOMAIN-SUFFIX,ipip.net,DIRECT
  - DOMAIN-SUFFIX,iqiyi.com,DIRECT
  - DOMAIN-SUFFIX,jd.com,DIRECT
  - DOMAIN-SUFFIX,jianshu.com,DIRECT
  - DOMAIN-SUFFIX,knewone.com,DIRECT
  - DOMAIN-SUFFIX,le.com,DIRECT
  - DOMAIN-SUFFIX,lecloud.com,DIRECT
  - DOMAIN-SUFFIX,lemicp.com,DIRECT
  - DOMAIN-SUFFIX,licdn.com,DIRECT
  - DOMAIN-SUFFIX,luoo.net,DIRECT
  - DOMAIN-SUFFIX,meituan.com,DIRECT
  - DOMAIN-SUFFIX,meituan.net,DIRECT
  - DOMAIN-SUFFIX,mi.com,DIRECT
  - DOMAIN-SUFFIX,miaopai.com,DIRECT
  - DOMAIN-SUFFIX,microsoft.com,DIRECT
  - DOMAIN-SUFFIX,microsoftonline.com,DIRECT
  - DOMAIN-SUFFIX,miui.com,DIRECT
  - DOMAIN-SUFFIX,miwifi.com,DIRECT
  - DOMAIN-SUFFIX,mob.com,DIRECT
  - DOMAIN-SUFFIX,netease.com,DIRECT
  - DOMAIN-SUFFIX,office.com,DIRECT
  - DOMAIN-KEYWORD,officecdn,DIRECT
  - DOMAIN-SUFFIX,office365.com,DIRECT
  - DOMAIN-SUFFIX,oschina.net,DIRECT
  - DOMAIN-SUFFIX,ppsimg.com,DIRECT
  - DOMAIN-SUFFIX,pstatp.com,DIRECT
  - DOMAIN-SUFFIX,qcloud.com,DIRECT
  - DOMAIN-SUFFIX,qdaily.com,DIRECT
  - DOMAIN-SUFFIX,qdmm.com,DIRECT
  - DOMAIN-SUFFIX,qhimg.com,DIRECT
  - DOMAIN-SUFFIX,qhres.com,DIRECT
  - DOMAIN-SUFFIX,qidian.com,DIRECT
  - DOMAIN-SUFFIX,qihucdn.com,DIRECT
  - DOMAIN-SUFFIX,qiniu.com,DIRECT
  - DOMAIN-SUFFIX,qiniucdn.com,DIRECT
  - DOMAIN-SUFFIX,qiyipic.com,DIRECT
  - DOMAIN-SUFFIX,qq.com,DIRECT
  - DOMAIN-SUFFIX,qqurl.com,DIRECT
  - DOMAIN-SUFFIX,rarbg.to,DIRECT
  - DOMAIN-SUFFIX,ruguoapp.com,DIRECT
  - DOMAIN-SUFFIX,segmentfault.com,DIRECT
  - DOMAIN-SUFFIX,sinaapp.com,DIRECT
  - DOMAIN-SUFFIX,smzdm.com,DIRECT
  - DOMAIN-SUFFIX,sogou.com,DIRECT
  - DOMAIN-SUFFIX,sogoucdn.com,DIRECT
  - DOMAIN-SUFFIX,sohu.com,DIRECT
  - DOMAIN-SUFFIX,soku.com,DIRECT
  - DOMAIN-SUFFIX,speedtest.net,DIRECT
  - DOMAIN-SUFFIX,sspai.com,DIRECT
  - DOMAIN-SUFFIX,suning.com,DIRECT
  - DOMAIN-SUFFIX,taobao.com,DIRECT
  - DOMAIN-SUFFIX,tencent.com,DIRECT
  - DOMAIN-SUFFIX,tenpay.com,DIRECT
  - DOMAIN-SUFFIX,tianyancha.com,DIRECT
  - DOMAIN-SUFFIX,tmall.com,DIRECT
  - DOMAIN-SUFFIX,tudou.com,DIRECT
  - DOMAIN-SUFFIX,umetrip.com,DIRECT
  - DOMAIN-SUFFIX,upaiyun.com,DIRECT
  - DOMAIN-SUFFIX,upyun.com,DIRECT
  - DOMAIN-SUFFIX,veryzhun.com,DIRECT
  - DOMAIN-SUFFIX,weather.com,DIRECT
  - DOMAIN-SUFFIX,weibo.com,DIRECT
  - DOMAIN-SUFFIX,xiami.com,DIRECT
  - DOMAIN-SUFFIX,xiami.net,DIRECT
  - DOMAIN-SUFFIX,xiaomicp.com,DIRECT
  - DOMAIN-SUFFIX,ximalaya.com,DIRECT
  - DOMAIN-SUFFIX,xmcdn.com,DIRECT
  - DOMAIN-SUFFIX,xunlei.com,DIRECT
  - DOMAIN-SUFFIX,yhd.com,DIRECT
  - DOMAIN-SUFFIX,yihaodianimg.com,DIRECT
  - DOMAIN-SUFFIX,yinxiang.com,DIRECT
  - DOMAIN-SUFFIX,ykimg.com,DIRECT
  - DOMAIN-SUFFIX,youdao.com,DIRECT
  - DOMAIN-SUFFIX,youku.com,DIRECT
  - DOMAIN-SUFFIX,zealer.com,DIRECT
  - DOMAIN-SUFFIX,zhihu.com,DIRECT
  - DOMAIN-SUFFIX,zhimg.com,DIRECT
  - DOMAIN-SUFFIX,zimuzu.tv,DIRECT
  - DOMAIN-KEYWORD,netflix,代理组名称
  - DOMAIN-KEYWORD,nflx,代理组名称
  ## 抗 DNS 污染
  - DOMAIN-KEYWORD,amazon,代理组名称
  - DOMAIN-KEYWORD,google,代理组名称
  - DOMAIN-KEYWORD,gmail,代理组名称
  - DOMAIN-KEYWORD,youtube,代理组名称
  - DOMAIN-KEYWORD,facebook,代理组名称
  - DOMAIN-SUFFIX,fb.me,代理组名称
  - DOMAIN-SUFFIX,fbcdn.net,代理组名称
  - DOMAIN-KEYWORD,twitter,代理组名称
  - DOMAIN-KEYWORD,instagram,代理组名称
  - DOMAIN-KEYWORD,dropbox,代理组名称
  - DOMAIN-SUFFIX,twimg.com,代理组名称
  - DOMAIN-KEYWORD,blogspot,代理组名称
  - DOMAIN-SUFFIX,youtu.be,代理组名称
  - DOMAIN-KEYWORD,whatsapp,代理组名称
  - DOMAIN-KEYWORD,googleapis,代理组名称
  # Clubhouse
  - DOMAIN-SUFFIX,clubhouse.com,代理组名称
  - DOMAIN-SUFFIX,clubhouseapi.com,代理组名称
  - DOMAIN-SUFFIX,joinclubhouse.com,代理组名称
  - DOMAIN-SUFFIX,clubhouseprod.s3.amazonaws.com,代理组名称
  - DOMAIN-SUFFIX,clubhouse.pubnub.com,代理组名称

  - DOMAIN-SUFFIX, ap-oversea-tls.agora.io, DIRECT
  - DOMAIN-SUFFIX, ap-oversea.agora.io, DIRECT
  - DOMAIN-SUFFIX, ap-oversea2.agora.io, DIRECT
  - DOMAIN-SUFFIX, report-oversea.agora.io, DIRECT
  - IP-CIDR, 3.0.163.78/32, DIRECT
  - IP-CIDR, 13.230.60.35/32, DIRECT
  - IP-CIDR, 23.248.191.103/32, DIRECT
  - IP-CIDR, 23.248.191.105/32, DIRECT
  - IP-CIDR, 23.98.43.152/32, DIRECT
  - IP-CIDR, 35.178.208.187/32, DIRECT
  - IP-CIDR, 45.40.48.11/32, DIRECT
  - IP-CIDR, 45.255.124.98/32, DIRECT
  - IP-CIDR, 45.255.124.100/32, DIRECT
  - IP-CIDR, 45.255.124.101/32, DIRECT
  - IP-CIDR, 45.255.124.104/32, DIRECT
  - IP-CIDR, 45.255.124.105/32, DIRECT
  - IP-CIDR, 45.255.124.107/32, DIRECT
  - IP-CIDR, 45.255.124.108/32, DIRECT
  - IP-CIDR, 45.255.124.109/32, DIRECT
  - IP-CIDR, 45.255.124.135/32, DIRECT
  - IP-CIDR, 50.17.126.121/32, DIRECT
  - IP-CIDR, 52.52.84.170/32, DIRECT
  - IP-CIDR, 52.58.56.244/32, DIRECT
  - IP-CIDR, 52.194.158.59/32, DIRECT
  - IP-CIDR, 52.221.46.208/32, DIRECT
  - IP-CIDR, 54.178.26.110/32, DIRECT
  - IP-CIDR, 69.28.51.148/32, DIRECT
  - IP-CIDR, 103.59.49.10/32, DIRECT
  - IP-CIDR, 103.65.41.166/32, DIRECT
  - IP-CIDR, 103.65.41.169/32, DIRECT
  - IP-CIDR, 103.98.18.181/32, DIRECT
  - IP-CIDR, 103.98.18.183/32, DIRECT
  - IP-CIDR, 103.98.18.184/32, DIRECT
  - IP-CIDR, 103.98.18.189/32, DIRECT
  - IP-CIDR, 120.227.115.126/32, DIRECT
  - IP-CIDR, 122.10.255.165/32, DIRECT
  - IP-CIDR, 128.1.87.196/32, DIRECT
  - IP-CIDR, 129.227.71.203/32, DIRECT
  - IP-CIDR, 129.227.115.130/32, DIRECT
  - IP-CIDR, 148.153.126.146/32, DIRECT
  - IP-CIDR, 148.153.172.73/32, DIRECT
  - IP-CIDR, 148.153.172.74/32, DIRECT
  - IP-CIDR, 148.153.172.75/32, DIRECT
  - IP-CIDR, 148.153.172.76/32, DIRECT
  - IP-CIDR, 148.153.172.77/32, DIRECT
  - IP-CIDR, 164.52.0.244/32, DIRECT
  - IP-CIDR, 164.52.6.19/32, DIRECT
  - IP-CIDR, 164.52.6.21/32, DIRECT
  - IP-CIDR, 164.52.6.23/32, DIRECT
  - IP-CIDR, 164.52.6.24/32, DIRECT
  - IP-CIDR, 164.52.6.25/32, DIRECT
  - IP-CIDR, 164.52.32.57/32, DIRECT
  - IP-CIDR, 164.52.32.59/32, DIRECT
  - IP-CIDR, 164.52.32.60/32, DIRECT
  - IP-CIDR, 164.52.36.228/32, DIRECT
  - IP-CIDR, 164.52.36.232/32, DIRECT
  - IP-CIDR, 164.52.36.238/32, DIRECT
  - IP-CIDR, 164.52.36.243/32, DIRECT
  - IP-CIDR, 164.52.36.245/32, DIRECT
  - IP-CIDR, 164.52.36.254/32, DIRECT
  - IP-CIDR, 164.52.102.35/32, DIRECT
  - IP-CIDR, 164.52.102.66/32, DIRECT
  - IP-CIDR, 164.52.102.67/32, DIRECT
  - IP-CIDR, 164.52.102.68/32, DIRECT
  - IP-CIDR, 164.52.102.69/32, DIRECT
  - IP-CIDR, 164.52.102.70/32, DIRECT
  - IP-CIDR, 164.52.102.75/32, DIRECT
  - IP-CIDR, 164.52.102.76/32, DIRECT
  - IP-CIDR, 164.52.102.77/32, DIRECT
  - IP-CIDR, 164.52.102.91/32, DIRECT
  - IP-CIDR, 164.52.124.102/32, DIRECT
  - IP-CIDR, 199.190.44.36/32, DIRECT
  - IP-CIDR, 199.190.44.37/32, DIRECT
  - IP-CIDR, 202.181.136.106/32, DIRECT
  - IP-CIDR, 202.226.25.162/32, DIRECT
  - IP-CIDR, 202.226.25.166/32, DIRECT
  - IP-CIDR, 202.226.25.171/32, DIRECT
  - IP-CIDR, 202.226.25.195/32, DIRECT
  - IP-CIDR, 202.226.25.198/32, DIRECT
  - IP-CIDR, 129.227.57.143/32, DIRECT
  - IP-CIDR, 129.227.234.70/32, DIRECT
  - IP-CIDR, 129.227.234.82/32, DIRECT
  - IP-CIDR, 129.227.234.119/32, DIRECT
  - IP-CIDR, 129.227.71.144/32, DIRECT
  - IP-CIDR, 129.227.57.132/32, DIRECT
  - IP-CIDR, 129.227.57.134/32, DIRECT
  - IP-CIDR, 129.227.57.145/32, DIRECT
  - IP-CIDR, 129.227.71.141/32, DIRECT
  - IP-CIDR, 129.227.234.83/32, DIRECT
  - IP-CIDR, 129.227.71.142/32, DIRECT
  - IP-CIDR, 129.227.71.132/32, DIRECT
  - IP-CIDR, 129.227.71.133/32, DIRECT
  - IP-CIDR, 129.227.71.134/32, DIRECT
  - IP-CIDR, 129.227.234.67/32, DIRECT
  - IP-CIDR, 129.227.234.110/32, DIRECT
  - IP-CIDR, 129.227.234.112/32, DIRECT
  - IP-CIDR, 129.227.234.124/32, DIRECT
  - IP-CIDR, 129.227.71.140/32, DIRECT
  - IP-CIDR, 129.227.71.130/32, DIRECT
  - IP-CIDR, 129.227.71.131/32, DIRECT
  - IP-CIDR, 129.227.71.143/32, DIRECT
  - IP-CIDR, 129.227.156.17/32, DIRECT
  - IP-CIDR, 129.227.57.137/32, DIRECT
  - IP-CIDR, 129.227.156.20/32, DIRECT
  ## 国外网站
  - DOMAIN-SUFFIX,openai.com,代理组名称
  - DOMAIN-SUFFIX,9to5mac.com,代理组名称
  - DOMAIN-SUFFIX,abpchina.org,代理组名称
  - DOMAIN-SUFFIX,adblockplus.org,代理组名称
  - DOMAIN-SUFFIX,adobe.com,代理组名称
  - DOMAIN-SUFFIX,alfredapp.com,代理组名称
  - DOMAIN-SUFFIX,amplitude.com,代理组名称
  - DOMAIN-SUFFIX,ampproject.org,代理组名称
  - DOMAIN-SUFFIX,android.com,代理组名称
  - DOMAIN-SUFFIX,angularjs.org,代理组名称
  - DOMAIN-SUFFIX,aolcdn.com,代理组名称
  - DOMAIN-SUFFIX,apkpure.com,代理组名称
  - DOMAIN-SUFFIX,appledaily.com,代理组名称
  - DOMAIN-SUFFIX,appshopper.com,代理组名称
  - DOMAIN-SUFFIX,appspot.com,代理组名称
  - DOMAIN-SUFFIX,arcgis.com,代理组名称
  - DOMAIN-SUFFIX,archive.org,代理组名称
  - DOMAIN-SUFFIX,armorgames.com,代理组名称
  - DOMAIN-SUFFIX,aspnetcdn.com,代理组名称
  - DOMAIN-SUFFIX,att.com,代理组名称
  - DOMAIN-SUFFIX,awsstatic.com,代理组名称
  - DOMAIN-SUFFIX,azureedge.net,代理组名称
  - DOMAIN-SUFFIX,azurewebsites.net,代理组名称
  - DOMAIN-SUFFIX,bing.com,代理组名称
  - DOMAIN-SUFFIX,bintray.com,代理组名称
  - DOMAIN-SUFFIX,bit.com,代理组名称
  - DOMAIN-SUFFIX,bit.ly,代理组名称
  - DOMAIN-SUFFIX,bitbucket.org,代理组名称
  - DOMAIN-SUFFIX,bjango.com,代理组名称
  - DOMAIN-SUFFIX,bkrtx.com,代理组名称
  - DOMAIN-SUFFIX,blog.com,代理组名称
  - DOMAIN-SUFFIX,blogcdn.com,代理组名称
  - DOMAIN-SUFFIX,blogger.com,代理组名称
  - DOMAIN-SUFFIX,blogsmithmedia.com,代理组名称
  - DOMAIN-SUFFIX,blogspot.com,代理组名称
  - DOMAIN-SUFFIX,blogspot.hk,代理组名称
  - DOMAIN-SUFFIX,bloomberg.com,代理组名称
  - DOMAIN-SUFFIX,box.com,代理组名称
  - DOMAIN-SUFFIX,box.net,代理组名称
  - DOMAIN-SUFFIX,cachefly.net,代理组名称
  - DOMAIN-SUFFIX,chromium.org,代理组名称
  - DOMAIN-SUFFIX,cl.ly,代理组名称
  - DOMAIN-SUFFIX,cloudflare.com,代理组名称
  - DOMAIN-SUFFIX,cloudfront.net,代理组名称
  - DOMAIN-SUFFIX,cloudmagic.com,代理组名称
  - DOMAIN-SUFFIX,cmail19.com,代理组名称
  - DOMAIN-SUFFIX,cnet.com,代理组名称
  - DOMAIN-SUFFIX,cocoapods.org,代理组名称
  - DOMAIN-SUFFIX,comodoca.com,代理组名称
  - DOMAIN-SUFFIX,crashlytics.com,代理组名称
  - DOMAIN-SUFFIX,culturedcode.com,代理组名称
  - DOMAIN-SUFFIX,d.pr,代理组名称
  - DOMAIN-SUFFIX,danilo.to,代理组名称
  - DOMAIN-SUFFIX,dayone.me,代理组名称
  - DOMAIN-SUFFIX,db.tt,代理组名称
  - DOMAIN-SUFFIX,deskconnect.com,代理组名称
  - DOMAIN-SUFFIX,disq.us,代理组名称
  - DOMAIN-SUFFIX,disqus.com,代理组名称
  - DOMAIN-SUFFIX,disquscdn.com,代理组名称
  - DOMAIN-SUFFIX,dnsimple.com,代理组名称
  - DOMAIN-SUFFIX,docker.com,代理组名称
  - DOMAIN-SUFFIX,dribbble.com,代理组名称
  - DOMAIN-SUFFIX,droplr.com,代理组名称
  - DOMAIN-SUFFIX,duckduckgo.com,代理组名称
  - DOMAIN-SUFFIX,dueapp.com,代理组名称
  - DOMAIN-SUFFIX,dytt8.net,代理组名称
  - DOMAIN-SUFFIX,edgecastcdn.net,代理组名称
  - DOMAIN-SUFFIX,edgekey.net,代理组名称
  - DOMAIN-SUFFIX,edgesuite.net,代理组名称
  - DOMAIN-SUFFIX,engadget.com,代理组名称
  - DOMAIN-SUFFIX,entrust.net,代理组名称
  - DOMAIN-SUFFIX,eurekavpt.com,代理组名称
  - DOMAIN-SUFFIX,evernote.com,代理组名称
  - DOMAIN-SUFFIX,fabric.io,代理组名称
  - DOMAIN-SUFFIX,fast.com,代理组名称
  - DOMAIN-SUFFIX,fastly.net,代理组名称
  - DOMAIN-SUFFIX,fc2.com,代理组名称
  - DOMAIN-SUFFIX,feedburner.com,代理组名称
  - DOMAIN-SUFFIX,feedly.com,代理组名称
  - DOMAIN-SUFFIX,feedsportal.com,代理组名称
  - DOMAIN-SUFFIX,fiftythree.com,代理组名称
  - DOMAIN-SUFFIX,firebaseio.com,代理组名称
  - DOMAIN-SUFFIX,flexibits.com,代理组名称
  - DOMAIN-SUFFIX,flickr.com,代理组名称
  - DOMAIN-SUFFIX,flipboard.com,代理组名称
  - DOMAIN-SUFFIX,g.co,代理组名称
  - DOMAIN-SUFFIX,gabia.net,代理组名称
  - DOMAIN-SUFFIX,geni.us,代理组名称
  - DOMAIN-SUFFIX,gfx.ms,代理组名称
  - DOMAIN-SUFFIX,ggpht.com,代理组名称
  - DOMAIN-SUFFIX,ghostnoteapp.com,代理组名称
  - DOMAIN-SUFFIX,git.io,代理组名称
  - DOMAIN-KEYWORD,github,代理组名称
  - DOMAIN-KEYWORD,linkedin,代理组名称
  - DOMAIN-SUFFIX,globalsign.com,代理组名称
  - DOMAIN-SUFFIX,gmodules.com,代理组名称
  - DOMAIN-SUFFIX,godaddy.com,代理组名称
  - DOMAIN-SUFFIX,golang.org,代理组名称
  - DOMAIN-SUFFIX,gongm.in,代理组名称
  - DOMAIN-SUFFIX,goo.gl,代理组名称
  - DOMAIN-SUFFIX,goodreaders.com,代理组名称
  - DOMAIN-SUFFIX,goodreads.com,代理组名称
  - DOMAIN-SUFFIX,gravatar.com,代理组名称
  - DOMAIN-SUFFIX,gstatic.com,代理组名称
  - DOMAIN-SUFFIX,gvt0.com,代理组名称
  - DOMAIN-SUFFIX,hockeyapp.net,代理组名称
  - DOMAIN-SUFFIX,hotmail.com,代理组名称
  - DOMAIN-SUFFIX,icons8.com,代理组名称
  - DOMAIN-SUFFIX,ift.tt,代理组名称
  - DOMAIN-SUFFIX,ifttt.com,代理组名称
  - DOMAIN-SUFFIX,iherb.com,代理组名称
  - DOMAIN-SUFFIX,imageshack.us,代理组名称
  - DOMAIN-SUFFIX,img.ly,代理组名称
  - DOMAIN-SUFFIX,imgur.com,代理组名称
  - DOMAIN-SUFFIX,imore.com,代理组名称
  - DOMAIN-SUFFIX,instapaper.com,代理组名称
  - DOMAIN-SUFFIX,ipn.li,代理组名称
  - DOMAIN-SUFFIX,is.gd,代理组名称
  - DOMAIN-SUFFIX,issuu.com,代理组名称
  - DOMAIN-SUFFIX,itgonglun.com,代理组名称
  - DOMAIN-SUFFIX,itun.es,代理组名称
  - DOMAIN-SUFFIX,ixquick.com,代理组名称
  - DOMAIN-SUFFIX,j.mp,代理组名称
  - DOMAIN-SUFFIX,js.revsci.net,代理组名称
  - DOMAIN-SUFFIX,jshint.com,代理组名称
  - DOMAIN-SUFFIX,jtvnw.net,代理组名称
  - DOMAIN-SUFFIX,justgetflux.com,代理组名称
  - DOMAIN-SUFFIX,kat.cr,代理组名称
  - DOMAIN-SUFFIX,klip.me,代理组名称
  - DOMAIN-SUFFIX,libsyn.com,代理组名称
  - DOMAIN-SUFFIX,linode.com,代理组名称
  - DOMAIN-SUFFIX,lithium.com,代理组名称
  - DOMAIN-SUFFIX,littlehj.com,代理组名称
  - DOMAIN-SUFFIX,live.com,代理组名称
  - DOMAIN-SUFFIX,live.net,代理组名称
  - DOMAIN-SUFFIX,livefilestore.com,代理组名称
  - DOMAIN-SUFFIX,llnwd.net,代理组名称
  - DOMAIN-SUFFIX,macid.co,代理组名称
  - DOMAIN-SUFFIX,macromedia.com,代理组名称
  - DOMAIN-SUFFIX,macrumors.com,代理组名称
  - DOMAIN-SUFFIX,mashable.com,代理组名称
  - DOMAIN-SUFFIX,mathjax.org,代理组名称
  - DOMAIN-SUFFIX,medium.com,代理组名称
  - DOMAIN-SUFFIX,mega.co.nz,代理组名称
  - DOMAIN-SUFFIX,mega.nz,代理组名称
  - DOMAIN-SUFFIX,megaupload.com,代理组名称
  - DOMAIN-SUFFIX,microsofttranslator.com,代理组名称
  - DOMAIN-SUFFIX,mindnode.com,代理组名称
  - DOMAIN-SUFFIX,mobile01.com,代理组名称
  - DOMAIN-SUFFIX,modmyi.com,代理组名称
  - DOMAIN-SUFFIX,msedge.net,代理组名称
  - DOMAIN-SUFFIX,myfontastic.com,代理组名称
  - DOMAIN-SUFFIX,name.com,代理组名称
  - DOMAIN-SUFFIX,nextmedia.com,代理组名称
  - DOMAIN-SUFFIX,nsstatic.net,代理组名称
  - DOMAIN-SUFFIX,nssurge.com,代理组名称
  - DOMAIN-SUFFIX,nyt.com,代理组名称
  - DOMAIN-SUFFIX,nytimes.com,代理组名称
  - DOMAIN-SUFFIX,omnigroup.com,代理组名称
  - DOMAIN-SUFFIX,onedrive.com,代理组名称
  - DOMAIN-SUFFIX,onenote.com,代理组名称
  - DOMAIN-SUFFIX,ooyala.com,代理组名称
  - DOMAIN-SUFFIX,openvpn.net,代理组名称
  - DOMAIN-SUFFIX,openwrt.org,代理组名称
  - DOMAIN-SUFFIX,orkut.com,代理组名称
  - DOMAIN-SUFFIX,osxdaily.com,代理组名称
  - DOMAIN-SUFFIX,outlook.com,代理组名称
  - DOMAIN-SUFFIX,ow.ly,代理组名称
  - DOMAIN-SUFFIX,paddleapi.com,代理组名称
  - DOMAIN-SUFFIX,parallels.com,代理组名称
  - DOMAIN-SUFFIX,parse.com,代理组名称
  - DOMAIN-SUFFIX,pdfexpert.com,代理组名称
  - DOMAIN-SUFFIX,periscope.tv,代理组名称
  - DOMAIN-SUFFIX,pinboard.in,代理组名称
  - DOMAIN-SUFFIX,pinterest.com,代理组名称
  - DOMAIN-SUFFIX,pixelmator.com,代理组名称
  - DOMAIN-SUFFIX,pixiv.net,代理组名称
  - DOMAIN-SUFFIX,playpcesor.com,代理组名称
  - DOMAIN-SUFFIX,playstation.com,代理组名称
  - DOMAIN-SUFFIX,playstation.com.hk,代理组名称
  - DOMAIN-SUFFIX,playstation.net,代理组名称
  - DOMAIN-SUFFIX,playstationnetwork.com,代理组名称
  - DOMAIN-SUFFIX,pushwoosh.com,代理组名称
  - DOMAIN-SUFFIX,rime.im,代理组名称
  - DOMAIN-SUFFIX,servebom.com,代理组名称
  - DOMAIN-SUFFIX,sfx.ms,代理组名称
  - DOMAIN-SUFFIX,shadowsocks.org,代理组名称
  - DOMAIN-SUFFIX,sharethis.com,代理组名称
  - DOMAIN-SUFFIX,shazam.com,代理组名称
  - DOMAIN-SUFFIX,skype.com,代理组名称
  - DOMAIN-SUFFIX,smartdnsProxy.com,代理组名称
  - DOMAIN-SUFFIX,smartmailcloud.com,代理组名称
  - DOMAIN-SUFFIX,sndcdn.com,代理组名称
  - DOMAIN-SUFFIX,sony.com,代理组名称
  - DOMAIN-SUFFIX,soundcloud.com,代理组名称
  - DOMAIN-SUFFIX,sourceforge.net,代理组名称
  - DOMAIN-SUFFIX,spotify.com,代理组名称
  - DOMAIN-SUFFIX,squarespace.com,代理组名称
  - DOMAIN-SUFFIX,sstatic.net,代理组名称
  - DOMAIN-SUFFIX,st.luluku.pw,代理组名称
  - DOMAIN-SUFFIX,stackoverflow.com,代理组名称
  - DOMAIN-SUFFIX,startpage.com,代理组名称
  - DOMAIN-SUFFIX,staticflickr.com,代理组名称
  - DOMAIN-SUFFIX,steamcommunity.com,代理组名称
  - DOMAIN-SUFFIX,symauth.com,代理组名称
  - DOMAIN-SUFFIX,symcb.com,代理组名称
  - DOMAIN-SUFFIX,symcd.com,代理组名称
  - DOMAIN-SUFFIX,tapbots.com,代理组名称
  - DOMAIN-SUFFIX,tapbots.net,代理组名称
  - DOMAIN-SUFFIX,tdesktop.com,代理组名称
  - DOMAIN-SUFFIX,techcrunch.com,代理组名称
  - DOMAIN-SUFFIX,techsmith.com,代理组名称
  - DOMAIN-SUFFIX,thepiratebay.org,代理组名称
  - DOMAIN-SUFFIX,theverge.com,代理组名称
  - DOMAIN-SUFFIX,time.com,代理组名称
  - DOMAIN-SUFFIX,timeinc.net,代理组名称
  - DOMAIN-SUFFIX,tiny.cc,代理组名称
  - DOMAIN-SUFFIX,tinypic.com,代理组名称
  - DOMAIN-SUFFIX,tmblr.co,代理组名称
  - DOMAIN-SUFFIX,todoist.com,代理组名称
  - DOMAIN-SUFFIX,trello.com,代理组名称
  - DOMAIN-SUFFIX,trustasiassl.com,代理组名称
  - DOMAIN-SUFFIX,tumblr.co,代理组名称
  - DOMAIN-SUFFIX,tumblr.com,代理组名称
  - DOMAIN-SUFFIX,tweetdeck.com,代理组名称
  - DOMAIN-SUFFIX,tweetmarker.net,代理组名称
  - DOMAIN-SUFFIX,twitch.tv,代理组名称
  - DOMAIN-SUFFIX,txmblr.com,代理组名称
  - DOMAIN-SUFFIX,typekit.net,代理组名称
  - DOMAIN-SUFFIX,ubertags.com,代理组名称
  - DOMAIN-SUFFIX,ublock.org,代理组名称
  - DOMAIN-SUFFIX,ubnt.com,代理组名称
  - DOMAIN-SUFFIX,ulyssesapp.com,代理组名称
  - DOMAIN-SUFFIX,urchin.com,代理组名称
  - DOMAIN-SUFFIX,usertrust.com,代理组名称
  - DOMAIN-SUFFIX,v.gd,代理组名称
  - DOMAIN-SUFFIX,vimeo.com,代理组名称
  - DOMAIN-SUFFIX,vimeocdn.com,代理组名称
  - DOMAIN-SUFFIX,vine.co,代理组名称
  - DOMAIN-SUFFIX,vivaldi.com,代理组名称
  - DOMAIN-SUFFIX,vox-cdn.com,代理组名称
  - DOMAIN-SUFFIX,vsco.co,代理组名称
  - DOMAIN-SUFFIX,vultr.com,代理组名称
  - DOMAIN-SUFFIX,w.org,代理组名称
  - DOMAIN-SUFFIX,w3schools.com,代理组名称
  - DOMAIN-SUFFIX,webtype.com,代理组名称
  - DOMAIN-SUFFIX,wikiwand.com,代理组名称
  - DOMAIN-SUFFIX,wikileaks.org,代理组名称
  - DOMAIN-SUFFIX,wikimedia.org,代理组名称
  - DOMAIN-SUFFIX,wikipedia.com,代理组名称
  - DOMAIN-SUFFIX,wikipedia.org,代理组名称
  - DOMAIN-SUFFIX,windows.com,代理组名称
  - DOMAIN-SUFFIX,windows.net,代理组名称
  - DOMAIN-SUFFIX,wire.com,代理组名称
  - DOMAIN-SUFFIX,wordpress.com,代理组名称
  - DOMAIN-SUFFIX,workflowy.com,代理组名称
  - DOMAIN-SUFFIX,wp.com,代理组名称
  - DOMAIN-SUFFIX,wsj.com,代理组名称
  - DOMAIN-SUFFIX,wsj.net,代理组名称
  - DOMAIN-SUFFIX,xda-developers.com,代理组名称
  - DOMAIN-SUFFIX,xeeno.com,代理组名称
  - DOMAIN-SUFFIX,xiti.com,代理组名称
  - DOMAIN-SUFFIX,yahoo.com,代理组名称
  - DOMAIN-SUFFIX,yimg.com,代理组名称
  - DOMAIN-SUFFIX,ying.com,代理组名称
  - DOMAIN-SUFFIX,yoyo.org,代理组名称
  - DOMAIN-SUFFIX,ytimg.com,代理组名称
  - DOMAIN-SUFFIX,telegram.me,代理组名称
  - DOMAIN-SUFFIX,v2ex.com,代理组名称
  - DOMAIN-SUFFIX,poe.com,代理组名称
  - DOMAIN-SUFFIX,poecdn.net,代理组名称
  - DOMAIN-SUFFIX,quoracdn.net,代理组名称
  - IP-CIDR,91.108.4.0/22,代理组名称
  - IP-CIDR,91.108.8.0/22,代理组名称
  - IP-CIDR,91.108.56.0/22,代理组名称
  - IP-CIDR,109.239.140.0/24,代理组名称
  - IP-CIDR,149.154.160.0/20,代理组名称
  - IP-CIDR,127.0.0.0/8,DIRECT
  - IP-CIDR,172.16.0.0/12,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT
  - IP-CIDR,10.0.0.0/8,DIRECT
  - IP-CIDR,17.0.0.0/8,DIRECT
  - IP-CIDR,100.64.0.0/10,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,代理组名称

实际使用的时候只需要把服务器信息填进去即可。

一点总结

这次折腾其实也算是一个小小的教训：很多时候我们用一套方案久了，就很少再去关注新的技术变化。

从 Shadowsocks 到 Xray 的 Reality，其实整个代理技术这几年变化还挺大的。

Reality 的思路本质上是让流量看起来更像正常的 TLS 连接，从而降低被识别的概率。配置虽然比早期的 Shadowsocks 稍微复杂一点，但整体来说稳定性确实更好。

当然，对大多数人来说，可能直接使用现成服务会更省事。但如果像我一样喜欢折腾服务器，这种自己一步步搭起来的过程，其实也挺有意思的。

至少下次再遇到问题的时候，大概也知道该从哪里开始排查了。

‍

从番剧墙到一个 Go CLI 工具

Thu, 26 Feb 2026 04:58:27 GMT

前段时间我把自己的网站整理了一下，做了一个“番剧墙 / 影视墙”的页面。

每个作品有封面、标题、评分、简介，看起来很清爽，也算是给自己这些年的观看记录做一个归档。

一开始我也想过，这些信息要不要手动整理。

理论上当然可以，但当数量慢慢多起来之后，问题就变得很现实：

封面图从哪里来？
简介要不要自己维护？
某个平台没有这部作品怎么办？

后来我了解到了 TMDB。

它是一个由全球社区共同维护的影视数据库，电影和剧集信息都很完整，也有免费的开放 API。如果是动态网站，直接在前端或服务端请求接口就能拿到数据，非常方便。

但我的博客是静态博客。

这意味着每一次构建都不太适合去实时请求外部 API，也不太希望页面强依赖外部接口的可用性。

另外还有网络、图片外链、访问速度等问题。

并且这些数据并非是变动频繁的数据，更多情况下数据只要产生了就完全不会变更了。

所以我换了个思路。

既然 TMDB 本身支持创建片单，那我是不是只需要维护一个“片单”，然后把片单数据一次性抓下来，转成我自己的静态数据？

于是就有了这个项目：

GitHub：tmdb-list-exporter

这个工具做了什么

它是一个用 Go 写的命令行工具。

输入一个 TMDB 片单名称，它会自动抓取这个片单中的全部影视信息，包括：

标题
评分
简介
封面路径
背景图路径
类型
上映时间等

然后导出为本地 JSON 文件。

图片可以选择直接使用 TMDB 原图链接，也可以下载到本地，或者上传到自己的 OSS。

对我来说，它的作用其实很简单：

我只需要维护 TMDB 上的片单，其余的数据处理交给工具完成。

这样我的网站构建阶段只读取本地 JSON 文件，不再依赖外部 API。

如果以后需要迁移主题或者改展示方式，也只需要重新生成一次数据。

为什么会想自己写

这其实不是一个复杂项目。

但它刚好卡在一个比较微妙的位置：

手动整理太麻烦
直接在线请求又不适合静态博客
已有工具要么偏重服务端，要么不太符合我的使用习惯

于是就干脆自己写一个。

这个项目的结构也比较简单，大概拆成几个模块：

tmdb：负责接口请求
image：处理图片下载
storage：本地或 OSS 存储
exporter：生成 JSON 文件

本质上它只是做了一次“数据搬运和整理”。

不过 CLI 项目本身对结构设计要求其实挺高的。

比如参数解析、错误处理、批量请求、不同平台打包，这些东西虽然不复杂，但做完整还是需要一点耐心。

我也顺便把它做成了多平台可执行文件，方便在不同环境下直接使用。

它解决的其实不是技术问题

做完之后再回头看，我觉得它真正带来的变化不是“我可以抓取 TMDB 数据”——

而是我不需要再手动维护一堆展示数据。

我只维护一个片单。

内容管理变成了“增删作品”这件事情本身，而不是围绕展示结构去改 JSON。

对于一个静态博客来说，这种拆分其实挺舒服的。

网站只是负责展示，数据生成是另外一个步骤。

关于我的番剧墙

这个工具目前主要服务于我自己的网站：查看我的番剧墙

我一直挺喜欢那种把观看记录长期整理下来的感觉。

像是一条时间轴，在不经意的时间打开一看就会感觉到一种类似于「自己居然已经经历过这么多了」的时间的流逝感。

对我来说，那更像是一份个人记录，而不是推荐列表。

这个小工具只是让这件事变得轻松了一点。

写在最后

项目本身不大，但它刚好是从一个真实的小需求出发，慢慢成型的。

如果你也在做类似的影视墙、番剧墙，或者希望把 TMDB 的片单数据转成自己的静态资产，也许可以用得上。

对我来说，它更多是一次对自己网站体系的补充，也是一次挺完整的 Go CLI 实践。

以后可能还会继续围绕自己的内容系统做一些小工具。

慢慢来。

用 Go 实现一个可长期运行的 GitHub Webhook 服务实践

Thu, 12 Feb 2026 07:07:34 GMT

前段时间我写过一篇文章，记录自己作为一名 PHP 开发者自学 Go 的过程

那篇更多是学习阶段的整理。这次则是一次完整实践的复盘。

单点知识和系统能力之间始终存在差距。

理解一个概念并不难，但要把多个能力组合起来，形成一个可以长期运行的系统，往往需要真实项目去反复打磨。很多看似基础的东西，只有亲手做过，理解才会真正扎实。

最近我完成了一个小工具：github-webhook-listener

一个用 Go 实现的 GitHub Webhook 接收服务，可以根据规则执行 Shell 命令，并内置一个简单的 Vue 面板，用于查看运行状态和执行记录。

功能本身并不复杂，AI 也完全可以在较短时间内生成类似的实现。但在实际开发过程中，我更在意的并不是功能本身，而是一些基础层面的设计问题：项目结构如何划分，依赖如何组织，边界如何定义，以及构建与部署如何简化。

这些内容未必新鲜，但当它们被组合到一个完整系统中时，体会是不同的。

项目地址我放在文章末尾，感兴趣可以自行查看下载使用。

下面我会从结构设计、并发模型以及构建方式三个方面，做一次相对完整的技术复盘。

项目结构与职责划分

项目核心代码放在 internal 目录：

internal/
├── bootstrap
├── handler
├── service
├── repository
├── model
├── dto

这种结构并不追求“标准答案”，重点在于依赖方向清晰。

repository

只负责数据库操作
不包含业务判断
不依赖 HTTP

service

负责业务逻辑
调用 repository
不处理 HTTP 细节

handler

只做参数解析与响应封装
调用 service
不包含核心逻辑

在功能简单时，这种分层似乎有些“多余”。

但当涉及到任务调度、执行记录、重试机制时，结构边界开始体现价值。

边界明确之后，功能扩展基本是“局部修改”，而不是结构性调整。

在 bootstrap 中组织依赖关系

所有初始化逻辑集中在 bootstrap 包中完成：

初始化数据库
创建 repository
注入到 service
注入到 handler
注册路由

依赖关系在入口处完全展开，而不是在各个文件中隐式创建。

这种方式带来的最大好处是：

对象生命周期清晰
依赖方向可控
替换实现时改动集中

在没有使用任何 DI 框架的情况下，通过显式构造函数完成依赖注入，本身就是对依赖关系的一种约束。

当项目规模不大时，这种方式反而比自动注入更透明。

双队列 Worker Pool 的并发调度模型

这个项目的核心之一，是执行 Shell 命令并控制并发数量。

我实现的是一个“双队列 Worker Pool”结构，主要包含三个核心组件：

任务生产者（Producer）
集中式调度器 + Worker Goroutine
结果处理器（Result Processor）

第一层：任务生产者

当 Webhook 触发或 Web 面板手动触发任务时，任务被封装为一个结构体，发送到调度队列。

这一层只负责“生成任务”，不关心执行细节。

第二层：集中式调度器 + Worker Pool

调度器内部维护：

一个任务输入队列
一个固定数量的 worker goroutine

调度流程：

调度器从任务队列中取出任务
分发给空闲 worker
worker 执行 Shell 命令
将执行结果发送到结果队列

worker 数量可控，因此系统并发是有上限的。

这种结构的优点：

并发可控
不会因为 Webhook 高频触发而无限创建 goroutine
任务调度逻辑集中管理

相比“每来一个请求直接开 goroutine 执行”的写法，这种结构在可控性和可扩展性上更好。

第三层：结果处理器

worker 不直接写数据库，而是把结果推送到结果队列。

结果处理器负责：

更新执行记录
写入数据库
处理重试逻辑（如果有）

这样做的目的，是进一步解耦：

执行逻辑专注执行
持久化逻辑专注记录

这就是“双队列”的意义：

队列一：任务调度
队列二：结果处理

这种分离在系统规模变大时尤为重要，因为执行耗时和持久化耗时是两个不同维度的问题。

Makefile 作为构建入口

项目使用 Makefile 统一管理：

后端构建
前端构建
交叉编译
发布打包

Makefile 在这里的意义并不是“少打几行命令”，而是：

所有构建流程被显式记录
新环境下可直接复现
发布步骤标准化

当一个项目开始涉及前后端协作、交叉编译和发布时，构建流程本身就成为项目的一部分。

使用 embed 将前端资源打包进二进制

这是我在这个项目中感受最明显的“Go 工程优势”。

前端使用 Vue 构建完成后，静态资源通过 embed 打包进 Go 二进制中。

然后通过：

http.FileServer(http.FS(...))

直接提供访问。

最终效果是：

只有一个可执行文件
不需要 Node 环境
不需要单独部署前端
不依赖外部静态文件目录

从架构上看，它仍然是前后端分离：

前端独立开发
后端提供 API

但从交付形态看，它又像是传统单体应用：

单文件分发
直接运行

这种组合非常适合工具型项目和内部服务。

Go 在这一点上确实有明显优势：编译后就是完整产物，不需要运行时环境，不依赖包管理器，不依赖额外解释器。

分发成本几乎为零。

写在最后

这个项目没有刻意追求复杂设计，也没有引入额外框架。

它更像是一次完整的工程实践：把分层、依赖组织、并发控制、构建管理这些已经学过的能力组合在一起，形成一个可长期运行的系统。

我自己已经在实际环境中持续使用它，用来自动化部署和执行脚本，稳定性和可维护性都符合预期。对我来说，它已经从“练手项目”变成了日常工具。

如果你刚好也需要一个简单的 GitHub Webhook 执行工具，可以直接拿去用；

如果你正在学习 Go，想找一个结构完整、但复杂度可控的小项目作为参考，也可以看看实现细节。

GitHub 仓库地址：点击查看

有问题或者想法，也欢迎直接在 GitHub 上交流。

从“能写 Go”到“写得对 Go”：一名 PHP 开发者的补课与重构

Thu, 08 Jan 2026 11:09:37 GMT

写在前面

我是一名从事了几年的 PHP 开发者，平时以独立开发为主。主流的 PHP 框架基本都接触过，也做过不少实际跑在线上的项目。

后来因为工作和个人兴趣的原因，开始逐渐接触 Go，也用 Go 做过一些真实的东西。

比如，用 Gin + Vue + Wails 做过 PC 应用，在 Ubuntu 服务器上跑过 Go 服务，也写过一些用于接收 GitHub Webhook 执行 shell 脚本的小工具。

从结果上看，这些项目都能正常运行，功能也正常。

但我自己很清楚，这并不等于我“真正掌握了 Go”。

很多时候，我其实是在用多年写 PHP 积累下来的直觉去写 Go。

代码能跑，但对一些关键细节并没有完全的确定感：struct、slice、map 到底是值还是引用，指针什么时候该用、什么时候不该用，并发写法会不会在某些场景下出问题，这些问题经常是靠经验和感觉在兜底。

说得直白一点就是：我能用 Go 干活，但并不总是确定自己写的是不是“对的 Go”。

市面上的 Go 教程大多从 0 开始，这对我来说反而有点不太合适，从头跟着学，会花大量时间在已经了解的内容上；跳着看，又很容易因为缺失上下文而看不明白真正重要的部分。

而我真正想补的，也并不是 Web 框架的用法，而是那些在 PHP 中不存在、却在 Go 中非常关键的基础差异。

为了逼自己真正学明白，也为了以后可以随时回看，我选择把整个过程整理成一篇持续更新的文章。

这不是一篇从 0 开始的 Go 入门教程，也不追求覆盖所有语言特性。

它更像是一名 PHP 开发者，在已经“能写 Go”的前提下，回头把那些一直靠感觉的地方重新补扎实的过程记录。

一、重新认识 Go

1. 为什么 Go 不适合用「脚本语言思维」去理解

如果之前没有接触过常驻内存框架，刚开始接触 Go 时，很容易下意识地用写 PHP、Python 这类脚本语言的方式去理解它：

无非是语法更严格一点、类型更强一点、性能更好一点。

在早期 PHP 那种“请求即生命周期”的模型下，这种理解其实是成立的。

一次请求执行完，进程结束，内存和状态被整体回收，很多问题都会被运行环境自然兜底，开发者也不需要太关心它们。

这几年，PHP 也出现了 webman、Swoole 这类 常驻内存框架，把 PHP 拉进了“长期运行服务”的世界。它们确实在使用体验上缩小了 PHP 和 Go 之间的距离，也让不少原本被隐藏的问题逐渐浮现出来。

但关键的区别在于：

Go 是从语言和运行时层面，就假设程序会长期运行；而 PHP 是在原有的脚本模型之上，通过框架去“补”这一点。

在 Go 里，长期运行不是一种特殊用法，而是一种 默认前提。

全局状态如何管理、资源如何释放、并发如何调度，这些问题不是“需不需要考虑”，而是语言和运行时必须正面解决的核心设计。

如果仍然用“写完就结束”的脚本思维去理解 Go，很容易忽略这些前提，写出那种 短期跑得通、长期一定会出问题 的代码。

所以，理解 Go 的关键，并不是把它当成“支持常驻内存的脚本语言”

而是意识到：它从一开始，就是为长期运行的服务而设计的语言。

2. Go 的编译模型、运行时与 PHP 的本质差异

Go 和 PHP 在使用体验上的差异，根源并不在语法层面，而在于它们背后的 编译模型和运行时设计。

PHP 本质上是一门 解释型脚本语言。

即便开启了 OPcache，代码依然是在运行时由 Zend VM 解析并执行的。

多年来，PHP 的语言和运行时设计始终围绕着“快速启动、快速执行、快速回收”展开，这也让它天然适配以请求为单位的执行模型。

Go 则是一门 编译型语言。

在 go build 阶段，源码会被编译成一个完整的可执行文件，语言本身、标准库以及运行时都会被整体打包进去。

程序启动时，Go 的 runtime 会先完成调度器、内存管理和 GC 的初始化，然后才进入 main 函数开始执行用户代码。

这带来的一个核心差异是：

PHP 更像是在“执行一段代码”，而 Go 更像是在“启动一个程序”。

在 Go 中，运行时并不是隐藏在背后的执行引擎，而是语言设计的一部分。

goroutine、调度模型、垃圾回收、并发语义，都是在语言层面就被明确建模的能力，而不是依赖框架或扩展后置补齐的功能。

因此，Go 的代码天然假设程序会长期存在，状态会被复用，资源需要被明确管理；

而 PHP 即便在常驻内存或长生命周期的框架下，语言本身依然保留着强烈的脚本时代特征：生命周期并不显式，状态容易通过全局或上下文隐式扩散，也缺乏语言级的并发原语。

并发能力更多是由框架或扩展提供，但开发者在写代码时，很容易默认“这是顺序执行的”。

这也解释了为什么，同样是在“做服务”，Go 更强调启动流程、生命周期和运行时行为，而 PHP 更关注单次请求的处理过程。

两者关注的重点，从一开始就不在同一个位置。

3. Go 项目结构与 `go mod` 的真实作用

如果你有 PHP 或前端背景，可以先把 go.mod 简单理解成 composer.json / package.json。

go mod tidy、go mod download 的使用体验，也确实很像 composer install。

在入门阶段，把它们都当作声明和管理项目依赖的工具，这个理解是完全成立的。

真正的差异不在“怎么写”，而在于：

依赖是在什么时候、以什么方式参与到程序里的。

在 PHP 或前端项目中，依赖代码会被拉进项目目录（vendor / node_modules），作为项目源码的一部分存在，并在运行时由解释器或运行环境加载；

而在 Go 中，依赖同样会被下载，但它们存在于 Go 的模块缓存中，不属于项目源码，只在编译阶段被解析、编译，并最终被打包进可执行文件。

这也决定了 go mod 的真实关注点：

它关心的并不是“运行时需要哪些库”，而是：

我要构建出一个什么样的程序。

同一份源码、同一份 go.mod，目标是无论在哪台机器上构建，最终得到的都是行为一致的二进制文件。依赖不是项目的一部分，而是构建过程中的输入。

基于这个前提，Go 的项目结构看起来就会非常克制。

目录结构更多是在表达 package 之间的编译关系，而不是应用层面的分层设计。

一个目录就是一个 package，package 是最小的编译和依赖单位，代码如何组织，本质上是在服务于“如何被编译”和“如何被发布”。

可以用下面这个对照，快速感受这种差异：

| 对比点 | PHP / 前端 | Go | | -------------- | --------------------------------- | ---------------------- | | 依赖声明文件 | composer.json / package.json | go.mod | | 安装依赖 | composer install / npm install | go mod tidy / download | | 依赖存放位置 | 项目目录（vendor / node_modules） | 模块缓存（不在项目中） | | 依赖参与阶段 | 运行时加载 | 编译期解析 | | 项目结构关注点 | 应用分层 | 包与编译边界 | | 最终产物 | 源码 + 运行环境 | 单一可执行文件 |

整体来看，go mod 表面上像是一个依赖管理工具，但它真正服务的是 Go 的编译模型。

这也是为什么 Go 项目往往结构简单、层级不多，却非常适合长期运行的工程型服务。

它从一开始，就把“如何构建”和“如何交付”放在了设计的核心位置。

4. package、import 与依赖边界（为什么 Go 讨厌循环依赖）

在 Go 中，package 是最核心的组织单位。

一个目录就是一个 package，而 package 同时也承担着编译边界、依赖边界和可见性边界这几件事情。

代码在 Go 里的归属关系，其实是先属于某个 package，再通过 import 被其他 package 使用，而不是一开始就挂在某个“项目”之下。

从这个角度看，import 在 Go 里也不是简单的“引用文件”，它更像是在明确声明一件事：

这个 package 在编译时依赖另一个 package 的产出结果。

所以，Go 的依赖关系，本质上是一张编译期的依赖图。

也正因为依赖是在编译期被严格确定的，Go 对 package 之间的依赖边界非常敏感，并且明确禁止循环依赖。

如果 A import B，B 又 import A，在不少脚本语言里，往往还能通过一些方式“绕过去”，比如延迟加载、运行时决定执行顺序等。

但在 Go 的模型里，这种关系本身就无法成立：编译器既无法确定编译顺序，也无法保证依赖结果是稳定的。

不过，禁止循环依赖的意义，并不只是“编译器做不到”。

从 Go 的设计取向来看，循环依赖本身就被视为一种值得警惕的结构信号，它通常意味着：

package 的职责边界不够清晰
抽象层级开始变得混乱
状态和逻辑在不同层之间相互牵扯

在这样的前提下，禁止循环依赖，实际上是在逼着你把依赖关系整理成单向的、有层次的结构。

这也是为什么在不少 Go 项目中，会逐渐形成一些比较一致的结构特征：

偏底层的 package 不依赖上层逻辑
通用能力被拆到更独立的 package 中
通过接口来反转依赖方向，而不是让 package 之间互相 import

换句话说，Go 并不是单纯在“语法层面不允许循环依赖”，而是通过语言规则，把依赖边界这件事提前暴露出来，让你在写代码的时候就必须面对它。

如果简单点来概括这种思路，大概可以这样理解：

在 Go 中，package 更像是在声明编译边界；
import 是在说明依赖方向；
禁止循环依赖，是为了让这些关系始终保持清晰和可推导。

二、值语义：PHP 开发者最容易踩的第一坑

5. struct 是值，不是对象

当前问题存在示例代码，可以前往GitHub查看

在 Go 里，有一个和 PHP 认知明显不同的地方：值语义。

在 PHP 中，我们通常把结构体或对象理解为有身份的实体：把它传给函数或者赋值给另一个变量，好像一直在操作同一份数据。

而在 Go 里，struct 的默认语义是值。这意味着一些看似自然的操作，其实背后发生的是复制：赋值会生成副本，函数传参会生成副本，方法调用在很多情况下也会生成副本。

type Counter struct {
	n int
}

a := Counter{n: 10}
b := a
b.n++
fmt.Println(a.n, b.n) // 10, 11

在这个例子里，虽然表面上只是一次赋值，但 a 和 b 已经是两份独立的数据。

从这个角度看，Go 并没有把共享状态作为默认行为，而是把 数据的传递与复制 放在了显式可见的位置。

6. 函数参数传递：值拷贝 vs 指针

当前问题存在示例代码，可以前往GitHub查看

值语义在函数参数传递上也会体现出来。

当 struct 作为函数参数传入时，Go 会生成一份副本：

func inc(c Counter) {
	c.n++
}

c := Counter{n: 10}
inc(c)
fmt.Println(c.n) // 10

可以看到，函数内部对 c 的修改没有影响外部的 c。如果希望函数内部修改能够影响外部，就需要使用指针：

func incPtr(c *Counter) {
	c.n++
}

incPtr(&c)
fmt.Println(c.n) // 11

方法调用遵循同样规则：接收者是值还是指针，决定了方法内部操作的是副本还是原始数据。

func (c Counter) incByValue()    { c.n++ }  // 操作副本
func (c *Counter) incByPointer() { c.n++ }  // 操作原值

c := Counter{n: 10}
c.incByValue()
fmt.Println(c.n) // 10

c.incByPointer()
fmt.Println(c.n) // 11

总结起来：

Go 的 struct 默认是值类型，赋值、函数传参、方法调用都会生成副本。
想要在函数或方法里修改原数据，需要显式使用指针。
slice、map、channel 等引用类型除外，它们内部数据的修改会反映到外部，但整体赋值仍然是复制副本。

相比 PHP 的对象语义，这种行为更加明确：共享必须被显式表达，而不是隐式存在。

7. 返回 struct、返回指针、返回 interface 的区别

当前问题存在示例代码，可以前往GitHub查看

在 Go 里，函数返回值既可以是值类型，也可以是指针类型，还可以是接口类型。我在学习中对这三种返回方式的行为做了观察，总结如下：

当函数返回一个 struct 时，返回的是一份副本。调用方拿到的是独立的数据，修改返回值不会影响函数内部或其他实例：

type Counter struct { n int }

func NewCounterVal() Counter {
	return Counter{n: 1}
}

c := NewCounterVal()
c.n++
fmt.Println(c.n) // 2

每次返回都是独立副本，适合小型 struct，不需要共享状态。内存上会复制整个 struct，如果 struct 较大，可能有开销。返回 struct 类似于函数传值，强调复制而非共享。

返回 struct 的指针时，调用方拿到的是原始对象的引用，可以修改原始数据：

func NewCounterPtr() *Counter {
	return &Counter{n: 1}
}

c1 := NewCounterPtr()
c2 := c1
c2.n++
fmt.Println(c1.n) // 2

返回值是指针，操作共享同一份数据，避免复制大型 struct，提高性能。修改原始数据变得显式可见，和函数传指针参数语义一致。

接口返回值稍微复杂一些。接口内部存储的是类型信息 + 值：如果返回值实现是 struct 值，接口内部存储的是副本；如果返回值实现是指针，接口内部存储的是指针，调用方法会修改原对象。

type Counterer interface {
	Inc()
	Value() int
}

func NewCounterInterface() Counterer {
	return &Counter{n: 1} // 返回指针实现
}

c := NewCounterInterface()
c.Inc()
fmt.Println(c.Value()) // 修改生效

接口返回行为取决于传入的是值类型实现还是指针类型实现。对 PHP 开发者来说，接口不像对象那样天然共享状态，需要理解内部存储机制。

| 返回类型 | 内部行为 | 是否共享原数据 | 适用场景 | | --------- | --------------- | -------------- | ------------------------ | | struct | 复制整个 struct | 否 | 小型 struct，不修改状态 | | *struct | 复制指针 | 是 | 修改状态或大型 struct | | interface | 存储值或指针 | 取决于实现 | 抽象类型，可存放值或指针 |

核心规律：Go 的函数返回值和参数传递类似，默认是值拷贝。想要共享原数据，需要显式使用指针。接口稍微复杂，需要理解内部存储机制。

8. 方法接收者：值接收者 vs 指针接收者

当前问题存在示例代码，可以前往GitHub查看

在 Go 中，方法本质上就是带接收者参数的函数：

func (c Counter) IncByValue()    { ... } // 值接收者
func (c *Counter) IncByPointer() { ... } // 指针接收者

接收者类型决定了方法内部修改是否会影响原对象。

值接收者方法内部操作的是副本，修改不会影响原对象。适合小型 struct 或只读操作：

c := Counter{n: 10}
c.IncByValue()
fmt.Println(c.n) // 10，原值不变

指针接收者方法内部操作的是原始对象，修改会反映到原对象。适合需要修改状态或大型 struct：

c := &Counter{n: 10}
c.IncByPointer()
fmt.Println(c.n) // 11，修改生效

方法接收者选择的原则大致如下：只读或小型 struct 可用值接收者；需要修改状态或大型 struct 通常用指针接收者；接口方法一般使用指针接收者，保证修改行为一致。

| 接收者类型 | 操作数据 | 是否修改原对象 | 适用场景 | | ---------- | -------- | -------------- | --------------------- | | 值接收者 | 副本 | 否 | 小 struct，只读操作 | | 指针接收者 | 原始对象 | 是 | 修改状态或大型 struct |

核心规律：方法接收者语义和参数传递一致，默认值传递，显式使用指针才能共享数据。

9. 「什么时候必须用指针」的经验法则

观察下来，大概可以这样理解：

修改原始数据的时候

方法或者函数内部如果希望改变外部的数据，必须用指针。

func IncPtr(c *Counter) { c.n++ }       // 参数是指针
func (c *Counter) Inc() { c.n++ }       // 方法接收者是指针

struct 较大或者复制成本明显的时候
- 当 struct 字段比较多，或者占用内存不小，传值会复制整个结构体。
- 指针传递可以避免这个复制开销，这时使用指针不是为了共享状态，而只是效率考虑。
```
func ProcessLargeStruct(s *LargeStruct) { ... } // 避免复制大对象
```
接口方法涉及内部状态修改
- 如果一个 struct 实现接口，方法会修改内部状态，那么接收者通常要用指针。
- 因为接口内部存的是类型 + 数据，如果传入的是值类型，实现方法会操作副本，修改不会反映到原对象。
```
func NewCounterInterface() Counterer {
    return &Counter{n:1} // 返回的是指针
}
```
希望行为统一或者更容易理解的时候
- 即便 struct 本身不大，如果想让所有方法行为一致，也可以统一用指针接收者。
- 这样方法调用不会因为值还是指针而表现不同，接口实现也更直观。

整理下来，我的理解可以这样总结：

必须修改原对象 → 用指针
struct 较大或复制开销明显 → 用指针
接口方法需要修改内部状态 → 用指针
希望行为统一 → 可以统一使用指针接收者

总体感觉是：Go 的默认行为是值语义，复制是自然发生的，共享状态不会自动发生，需要用指针显式表达。值类型适合只读或者独立副本操作，指针类型则可以让修改和共享变得明确。

三、指针：只学 Go 中真正需要的那一部分

10. `&` 和 `*` 的真实含义

当前问题存在示例代码，可以前往GitHub查看

刚接触 Go 的时候，我会下意识用 PHP 的视角去理解 & 和 *，把它们当成“引用传递”的另一种写法。但在实际对比之后，我发现这两个符号并不是在讨论“怎么传参”，而是在明确区分一件更基础的事情：当前操作的是值，还是值所在的位置。

在 PHP 中，这层区分基本是被隐藏的。变量更像是“名字指向值”，至于值是否被复制、是否共享，通常由运行时决定。即使使用 &，它也更偏向一种语义层面的开关，用来改变变量之间的绑定关系，而不是一个可以被单独拿出来传递、存储或返回的实体。某种程度上，PHP 的 & 已经把“位置”和“通过位置修改值”这两件事打包在一起了。

Go 的选择正好相反。& 表达的是一个非常具体的动作：把某个值所在的位置本身当作一个值暴露出来；* 则表示通过这个位置去访问或修改对应的数据。它们并不是在模拟 PHP 的引用语义，而是在显式引入“位置”这一概念，并要求调用方和使用方分别表态：一边决定是否交出位置，一边决定是否通过位置操作数据。

从这个角度看，函数签名里的差异就变得很直接了。参数是值，还是指向值的位置，在定义阶段就已经确定，不需要依赖函数内部实现来判断是否会产生副作用。这一点在 struct 上尤其明显：Go 中的 struct 是值，而不是对象，只有显式地传递位置，修改才会作用到同一份数据上。

因此，& 和 * 更像是一种边界标记。写下它们，并不只是为了“能改到外面的变量”，而是在明确区分“数据的副本”和“数据本身”。和 PHP 那种由语言替你处理这些细节的方式相比，Go 更倾向于把选择提前，并且要求你把这个选择直接写进代码里。

11. 指针并不是“性能优化工具”

在一开始理解指针的时候，很容易把它和“性能优化”直接挂钩，尤其是从 PHP 这种对内存细节高度抽象的语言过来时，会下意识认为：传指针是不是就是为了少一次拷贝、快一点。

但在实际对比之后，我更倾向于把指针理解为语义工具，而不是性能工具。它首先解决的并不是“快不快”，而是“这份数据是不是被共享、是不是允许被修改”。

在 Go 里，是否使用指针，直接影响的是代码表达的含义。一个函数接收值，意味着它只能操作这份数据的副本；一个函数接收指针，意味着它明确依赖并可能修改某个已有的数据。这种区分本身就是 API 设计的一部分，而不是隐藏在实现细节里的性能技巧。

当然，从结果上看，指针确实可能减少拷贝，尤其是在数据结构较大的情况下。但这是使用指针之后自然产生的副作用，而不是它存在的主要目的。Go 的编译器本身已经会在很多场景下帮你做逃逸分析和拷贝优化，如果只是为了“少拷一次”，往往并不需要手动引入指针。

更重要的是，一旦把指针当成性能工具使用，代码的语义边界反而会变得模糊。一个函数之所以接收指针，究竟是因为它需要修改外部状态，还是只是为了“快一点”，从签名上已经无法判断。这种不确定性，往往比那点拷贝成本更昂贵。

所以在 Go 里，是否使用指针，更像是在回答一个设计问题：这是不是一份需要被共享和协同修改的数据。性能因素当然存在，但它更适合出现在已经明确语义之后，而不是作为引入指针的第一理由。

12. nil 指针与零值的区别

在一开始接触 nil 的时候，我很容易把它和“空值”划等号，甚至会下意识地把它当成某种“默认的零”。但在 Go 里，对比下来会发现，nil 指针和零值并不在同一个层面上，它们描述的是两种不同的状态。

零值描述的是“这个类型本身处在一个合法但未初始化的状态”。比如一个 int 的零值是 0，一个 struct 的零值是各字段的零值组合。它们都是完整、可用的值，可以被读取、传递，也可以参与计算。零值关注的是“值是什么”。

nil 则更像是在回答另一个问题：这里有没有一个实际存在的东西。当一个指针是 nil，并不是说它指向的值是“空的”，而是说它根本没有指向任何位置。它关注的不是值的内容，而是“指向关系是否存在”。

这也是为什么同样是“什么都没初始化”，零值的 struct 可以直接使用，而 nil 指针却不能被解引用。前者是一个完整的值，只是内容处在默认状态；后者则缺少了最基本的前提——并不存在一个可以通过它访问的对象。

如果把这种差异放回到 PHP 的语境中，会更容易看清楚。PHP 的 null 更像是一种通用的“空”的表达：它既可能表示“没有值”，也可能表示“尚未初始化”或“没有结果”。同一个 null，在不同场景下承担的是不同的语义，更多是一种语言层面的兜底状态。

而 Go 并没有用 nil 去覆盖所有“空”的情况。一个 int 不可能是 nil，一个 struct 也不可能是 nil，因为它们本身就是值，始终是存在的。只有那些需要依附于某个底层实体的类型，才会有“存在 / 不存在”这层状态，因此才会出现 nil。这使得 nil 的含义相对单一，也更容易被约束。

从这个角度看，nil 本身并不是零值的替代品，而是一种额外的状态标记。是否允许出现 nil，本身就是 API 设计的一部分：返回零值，往往意味着“这是一个合法但内容处在默认状态的结果”；而返回 nil，则更明确地表达“这里没有结果”或者“这个对象尚未存在”。

因此，在 Go 里区分 nil 指针和零值，关键不在于语法差异，而在于它们各自表达的语义边界。相比 PHP 用 null 统一兜住各种“空”的情况，Go 更倾向于把“值是否存在”和“值的内容是什么”拆开表达，把选择和含义直接暴露在类型和签名中。

13. 指针在业务代码中的合理边界

它并不是用得越多越好，而是用来标记哪些数据具有共享和可变的属性。

在大多数业务场景里，值语义本身已经足够。请求参数、配置快照、计算中间结果，这些数据更像是一次性输入或阶段性产物，用值来传递反而更清晰：函数拿到的是一份拷贝，能做的事情是受限的，也更容易推断行为。

指针更适合出现在那些具有明确生命周期和身份的对象上。比如聚合根、长期存在的上下文、需要被多处协同修改的状态。这里使用指针，并不是为了避免拷贝，而是在表达：这不是一份临时数据，而是一个被持续引用和演化的实体。

从接口设计的角度看，指针往往意味着副作用是设计的一部分。如果一个函数接收指针，通常可以预期它会对外部状态产生影响；而只接收值的函数，则更接近于纯逻辑处理。这种区分一旦稳定下来，代码的可读性会比任何注释都强。

同时，指针的边界也应该尽量收敛。越靠近业务边缘，比如 handler、service 层，对指针的使用就越需要谨慎。指针在这些层级一旦被随意传递，很容易让状态修改在调用链中扩散，最终变成难以追踪的隐式依赖。相反，把指针限制在领域内部或基础设施层，往往更容易控制其影响范围。

所以在业务代码中，是否使用指针，更多是在回答一个设计问题：这里是不是一个需要被共享、被持续修改的对象。当这个问题的答案不明确时，优先选择值，通常会得到一个更稳定、更容易演进的结构。

14. Go 为什么不鼓励随意暴露指针

Go 并不是反对指针本身，而是不鼓励它被随意暴露。这种克制并不是出于安全限制，而更像是一种设计取向。

一旦指针被暴露出去，暴露的其实并不只是一个数据访问方式，而是对内部状态的直接操作权。拿到指针的一方，不需要经过任何额外的约束，就可以修改其指向的数据，这会让原本清晰的状态边界变得模糊。数据“属于谁”、由谁负责维护，不再只保持在定义处，而是开始向调用方扩散。

从 API 设计的角度看，指针会把实现细节向外泄漏。一个返回指针的函数，实际上是在告诉使用者：这里有一块可以被直接操作的内部数据。这种暴露一旦发生，后续的重构空间就会被压缩——内部结构是否还能调整、是否还能增加校验逻辑，都会受到限制。

相比之下，返回值或只接收值参数，意味着调用方只能通过你定义好的入口与数据交互。修改行为被集中在有限的函数中，状态变化路径也更容易被追踪。这并不会减少灵活性，而是在用结构换取长期的可维护性。

另外，指针的暴露还会影响代码的阅读方式。看到一个值，默认可以认为它是局部、受控的；看到一个指针，则需要额外思考它可能在什么地方被修改过。随着指针在调用链中不断传递，这种不确定性会迅速累积，最终让代码的理解成本超过它带来的便利。

因此，Go 对指针的克制使用，更像是在强调一件事：共享状态本身就是一种需要被谨慎对待的设计选择。指针并不是被禁止的工具，但它更适合被限制在清晰的边界之内，而不是作为默认的数据暴露方式存在。

四、slice：Go 中最“像魔法”的数据结构

15. slice 的底层结构：指针、长度、容量

当前问题存在示例代码，可以前往GitHub查看

一开始接触 slice 时，很容易从语法形式去理解它。

int、string 是具体类型，那 []int、[]string 看起来就像是“可以装多个值的版本”（可变数组）。

这种理解在使用层面基本成立，但在解释 slice 的一些行为时，总会出现不太连贯的地方，比如切出来的 slice 为什么会互相影响，append 为什么一定要接收返回值，或者 len 和 cap 为什么会呈现出不同的变化节奏。

把这些现象放在一起看，会逐渐意识到一个前提：slice 本身并不负责存放数据。

在 Go 里，真正承载数据的是 array。

array 的内存是连续、一次性分配的，长度固定；而 slice 更像是对这段内存的一种描述。与其把 slice 理解成“可变数组”，不如把它看成是对某一段连续内存的引用说明。

从实现角度看，slice 可以抽象成一个很小的结构，里面包含三类信息：指向底层数组中某个位置的指针、当前可以访问的长度，以及从这个位置开始到底层数组末尾的容量。slice 自身并不拥有数据，它只是标记了从哪里开始、当前能用多少、以及理论上还能扩展到哪里。

这个视角在切片操作中体现得非常直接。

arr := [5]int{1, 2, 3, 4, 5}
s := arr[1:4]

// s: [2 3 4]
// len: 3
// cap: 4

这里的 1:4 描述的是下标区间，而不是具体内容。

切片之后：

s 的起点指向 arr[1]
len(s) 为 3
cap(s) 从 arr[1] 一直延伸到数组末尾

slice 并没有复制任何数据，只是把指针向后挪了一格，并重新标注了可见范围和容量边界。对 slice 再进行切片，发生的事情也是类似的，只是在同一块底层数组上不断调整这些标记。

这也解释了为什么在观察 len 和 cap 时，它们的变化往往不同步。

s := []int{}
for i := 0; i < 6; i++ {
	s = append(s, i)
	fmt.Println(len(s), cap(s))
}
// 输出：
// 1 4
// 2 4
// 3 4
// 4 4
// 5 8
// 6 8

在这类输出中，len 会随着元素增加而线性增长，而 cap 则会在一段时间内保持不变，然后突然变大。len 描述的是当前已经使用的部分，而 cap 描述的是底层数组还能提供的空间大小，它们关注的是两个不同的边界。

当 append 发现继续写入会超过当前容量时，就会为 slice 分配一块新的底层数组，并把已有数据拷贝过去。从这一刻开始，新的 slice 就已经不再和之前那块内存绑定在一起了。

这也是为什么 append 的结果需要被重新赋值：你拿到的，可能已经是一个指向不同内存区域的 slice。

在此之前，如果多个 slice 是从同一个 array 或 slice 切出来的，那么它们很可能共享同一块底层数组。

在容量范围内对其中一个 slice 的修改，本质上都是在操作同一段内存；

只有当某一次扩容触发了重新分配，这种共享关系才会被打破。

这样再看 slice，它的定位会变得清晰一些。它既不是数组本身，也不是一个独立的容器，而是一种对连续内存的访问方式。

指针决定了起点，长度限定了当前可见的范围，容量则标记了还能向后延伸的边界。

16. slice ≠ array：为什么 append 会出问题

当前问题存在示例代码，可以前往GitHub查看

在理解了 slice 的底层结构之后，再回头看一些 append 的行为，就会发现问题并不出在 append 本身，而是出在对 slice 语义的预期上。

如果把 slice 当成一个“独立的、可变的数组”，那么很自然会认为：对一个 slice 的修改，不应该影响另一个看起来无关的 slice。但在 Go 里，这个前提并不成立。

slice 和 array 的差异，首先体现在它们“值”的含义上。array 的值本身就包含了全部数据，而 slice 的值只是描述了一段数据的位置和范围。

当 slice 被赋值、被切片、被传参时，被复制的只是这组描述信息，而不是底层的数据。

这种差异在 append 场景中会被放大。

s := make([]int, 0, 5) // 预先分配 5 cap
s = append(s, 1, 2, 3) // len == 3，len < cap 不会重新分配内存

a := s[:2]

此时，s 和 a 指向的是同一块底层数组，只是各自的 len 不同。如果接下来对 a 进行 append，并且追加的元素仍然落在 cap 范围内：

a = append(a, 4) // len == 4，len < cap 不会重新分配内存

那么这次写入实际上发生在那块共享的内存上。结果就是，a 的变化同时体现在了 s 上。从表面上看，这种行为容易让人产生“append 出问题了”的感觉，但从 slice 的定义来看，它只是如实地反映了底层内存的状态。

只有当继续追加，使得 a 的长度超过了当前容量：

a = append(a, 5, 6) // len == 6，len > cap 重新分配内存

Go 才会为 a 分配新的底层数组，并将原有数据拷贝过去。从这一刻开始，a 和 s 才真正指向了不同的内存区域，后续的修改也不再相互影响。

对比之下，array 不会出现类似情况。array 的赋值和传递都会拷贝全部数据，本身就不存在多个“视图”指向同一份数据的可能。

也正因为如此，如果下意识地用 array 的直觉去理解 slice，就很容易在 append 这样的场景中产生偏差。

这样再看“append 会出问题”这件事，问题的来源其实并不复杂：append 只是遵循了 slice 的内存模型，而反直觉的地方，来自于对 slice 角色的误判。

一旦接受 slice 只是视图而不是存储，这些行为就会显得更像是结构本身的自然结果。

17. 扩容带来的引用断裂问题

当前问题存在示例代码，可以前往GitHub查看

前面已经反复提到，slice 本身只是三元信息的组合：指针、长度、容量。

只要容量还没用尽，append 只是把数据继续写进同一块底层数组里，多个 slice 之间共享内存这一事实不会改变。

真正需要额外留意的，其实只有一种情况：扩容发生的时候。

一旦 append 触发扩容，Go 会重新分配一块更大的连续内存，把原有数据整体复制过去，然后返回一个指向新内存的 slice。

这个过程不会“通知”其他 slice，也不会修改它们的指针。结果就是：原本指向同一块底层数组的 slice，从这一刻开始，可能已经不再共享内存了。

这种变化在代码层面几乎是无感的：

a = append(a, x)

变量名没变，类型没变，但 slice 所描述的那段内存已经变了。

所谓的“引用断裂”，并不是某个 slice 出了问题，而是共享关系在扩容这一刻自然结束了。

如果把 slice 理解为“对一段连续内存的视图”，那么这个结果其实并不意外：连续内存无法原地变大，扩容只能搬迁；一旦搬迁，指针改变，共享关系也就随之结束。

18. slice 作为函数参数的常见误解

当前问题存在示例代码，可以前往GitHub查看

在把 slice 作为函数参数时，最容易产生的误解，其实只有一个：

以为 slice 传进去之后，就天然具备“引用语义”。

表面上看，这种感觉并不奇怪。

在函数里修改 slice 的元素，外部确实能看到变化：

func f(s []int) {
	s[0] = 100
}

a := []int{1, 2, 3}
f(a)
fmt.Println(a) // [100 2 3]

这很容易让人形成一种判断：slice 是“按引用传递”的。

但这个结论只在一个前提下成立：函数内外的 slice 仍然指向同一块底层数组。

一旦把 append 放进来，情况就变了：

func f(s []int) {
	s = append(s, 4)
}

a := []int{1, 2, 3}
f(a)
fmt.Println(a) // [1 2 3]

这里并不是 append 没生效，而是：

a 传入函数时，只拷贝了一份 slice 结构
append 可能触发扩容
新的 slice 指向了新的底层数组
外部的 a 从头到尾都没有被重新赋值

所以这个行为并不矛盾，只是前后关注的层级不一样：

修改元素，改的是底层数组
append，改的是 slice 自身（指针、len、cap）

而函数参数传递的，始终只是 slice 这个值。

从这个角度看，更准确的说法其实是：

slice 是值类型，但它的值里，包含了对底层数组的引用信息。

这也解释了为什么有些代码“看起来能改到外面”，但一旦规模变大、触发扩容，行为就突然变了。

所以在函数边界上，真正需要记住的并不多：

函数拿到的是 slice 的一份拷贝
是否影响外部，取决于是否仍然共享底层数组
一旦扩容发生，共享关系自然结束

理解这一点之后，slice 作为参数的行为，其实就不再有什么特殊之处了。

19. slice 在并发场景下的风险

当前问题存在示例代码，可以前往GitHub查看

这一块其实可以顺着前面的理解自然往下推，在并发场景里，slice 的“风险”并不是它有什么特殊规则，而是它把共享内存这件事隐藏得太轻了。

先说一个容易被忽略的事实：slice 本身是一个很小的值，但它描述的是一段真实存在的、连续的内存。

当多个 goroutine 同时持有“看起来是不同的 slice”，但它们实际上指向同一块底层数组时，并发风险就已经成立了。

比如这样一种情况：

base := make([]int, 0, 10)

a := base[:5]
b := base[2:7]

从代码层面看，a 和 b 是两个独立的变量；

从内存层面看，它们的可见范围是重叠的。

如果此时两个 goroutine 分别操作它们：

go func() {
	a[0] = 100
}()

go func() {
	b[0] = 200
}()

这里并不存在什么“slice 专属问题”，本质上就是多个 goroutine 在无同步的情况下写同一块内存。

危险之处在于：slice 的这种共享关系，往往不是显式写出来的，而是通过切片操作自然形成的。

另一个更隐蔽的风险，来自 append。

如果多个 goroutine 对同一个 slice 进行 append，问题并不只是“是否扩容”这么简单：

go func() {
	s = append(s, 1)
}()

go func() {
	s = append(s, 2)
}()

这里至少有几层不确定性：

len 的更新不是原子的
是否触发扩容，取决于时序
一次扩容可能让某个 goroutine 拿到新的底层数组
另一个 goroutine 仍然在操作旧的那一块

结果可能是数据丢失、覆盖，甚至直接触发 data race。

而最容易踩坑的地方在于： 即使不发生扩容，也依然是非线程安全的。

因为 append 在修改 slice 时，至少会同时修改：

底层数组中的元素
slice 自身的 len

这两件事都不是并发安全的。

所以在并发语境下，看待 slice 有一个比较稳妥的心智模型：

slice 不是并发安全的容器
共享 slice，本质上就是共享内存
只要存在写操作，就必须有同步手段

如果需要在多个 goroutine 之间安全地使用 slice，通常只有几种选择：

明确只读，不写
在外层用 mutex 保护所有访问
在 goroutine 之间传递 slice 的拷贝，而不是共享
或者在设计上避免 slice 成为共享状态

理解了 slice 的底层结构之后，这些结论其实都不突兀。

并发场景下的问题，并不是 slice “不可靠”，而是它对内存的描述能力太直接，而并发恰恰放大了这一点。

五、map：看起来简单，实则暗雷密布

20. map 是引用类型，但不是并发安全

当前问题存在示例代码，可以前往GitHub查看

在 Go 里，map[K]V 是用来做键值映射的类型。

最常见的用法，大概就是这样：

m := map[string]int{}
m["a"] = 1
m["b"] = 2

v := m["a"]

通过 key 读写 value，没有下标、没有顺序，也不关心元素在内存中的位置。

从使用体验上看，它更像一个“随手可用的关联表”。

而在把 map 用进实际代码之前，很容易先形成一个直觉判断：map 是引用类型。

这个判断来自它在函数间传递时的表现：

func f(m map[string]int) {
	m["x"] = 100
}

a := map[string]int{}
f(a)
fmt.Println(a) // map[x:100]

map 被作为参数传入函数，在函数里修改之后，外部能直接看到结果。

这和 slice 修改元素时的行为非常接近，也很自然地让人把 map 理解为“引用传递”。

但问题往往就出在这里。

如果顺着这个理解继续往前走，很容易下意识地认为：既然 map 是引用类型，那在并发场景下，它的行为也应该是稳定、可预期的。

事实恰好相反。

map 虽然表现得像引用，但它并不是并发安全的。

而且这个限制是非常明确的：只要存在并发写操作，哪怕只有一个读，都是不允许的。

从实现角度看，map 对应的是运行时维护的一张哈希表。

一次看似简单的写入，背后可能涉及 bucket 的调整、元素移动，甚至扩容过程。

这些操作都不是原子的，也没有为并发访问设计同步机制。

所以，map 的定位其实很清晰：

它在语义上是“引用式使用”的
但在并发模型上，默认假设只有一个 goroutine 在操作

这两点并不矛盾，只是很容易在直觉上被混在一起。

把这一层想清楚之后，后面关于 map 并发 panic、为什么必须加锁、为什么会有 sync.Map，其实都只是自然延伸而已。

21. nil map vs make(map)

当前问题存在示例代码，可以前往GitHub查看

在使用 map 时，很容易遇到两种看起来很接近的写法：

var m1 map[string]int
m2 := make(map[string]int)

从类型上看，它们都是 map[string]int，len 也同样是 0：

fmt.Println(len(m1)) // 0
fmt.Println(len(m2)) // 0

如果只停在这里，很容易觉得它们只是两种等价的初始化方式。

但实际使用中，很快就会发现它们的行为并不一样。

先看 nil map。

var m1 map[string]int 声明了一个 map 类型的变量，但并没有为它分配任何底层哈希表。

这个时候，m1 的值是 nil。

对 nil map 来说，有些操作是允许的：

v := m1["a"]      // 读
_, ok := m1["a"]  // 判断是否存在
l := len(m1)      // len

这些操作都不会 panic，结果也都很直观：读不到值，ok 为 false，长度为 0。

但一旦尝试写入：

m1["a"] = 1

程序会直接 panic。

原因并不复杂：写入 map 需要一个已经存在的哈希表，而 nil map 并没有任何底层结构可以写。

再看 make(map)：

m2 := make(map[string]int)

这里发生的事情是：运行时为 map 分配并初始化了一张空的哈希表。

从这一刻开始：

可以安全地读
可以安全地写
可以不断插入新的 key-value

所以，两者之间真正的区别不在“是不是空”，而在于：

nil map：类型存在，但底层结构不存在
make(map)：类型存在，底层结构也已经准备好

把这一点和前面关于“map 是引用式使用”的结论放在一起，其实就很好理解了。

map 这个值，本身就是一个指向运行时结构的引用；

nil map，只是这个引用还没指向任何东西。

从这个角度看，nil map 并不是一个“特殊的空容器”，而更像是一个尚未初始化的状态。

也正因为如此，实践中对 map 的态度往往会很明确：

如果只是读，nil map 完全可以接受
如果需要写，就必须确保 map 已经通过 make 初始化

22. map 在函数间传递的行为

当前问题存在示例代码，可以前往GitHub查看

在函数之间传递 map 时，最容易产生的直觉是：既然 map 是引用类型，那传来传去应该都指向同一个东西。

从使用结果看，这个直觉往往是“对的”：

func f(m map[string]int) {
	m["a"] = 1
}

func main() {
	m := make(map[string]int)
	f(m)
	fmt.Println(m) // map[a:1]
}

函数里对 map 的修改，外部可以直接看到，这和 slice 修改元素、或者指针参数的表现非常接近。

但如果只停在“引用类型”这个结论上，其实会漏掉一个很关键的层次：map 在函数间传递的，依然是一个值。

只不过，这个值内部保存的是对运行时哈希表的引用。

换个角度说：

map 变量本身是值语义
这个值里，指向的是一张共享的哈希表

所以，当你在函数里做的是修改表内容时，外部自然能看到变化；

但当你在函数里重新指向一张表时，情况就完全不同了。

比如：

func reset(m map[string]int) {
	m = make(map[string]int)
	m["a"] = 1
}

func main() {
	m := map[string]int{"x": 10}
	reset(m)
	fmt.Println(m) // map[x:10]
}

这里并不是 reset 没有生效，而是：

m 在函数参数处被拷贝了一份
make(map) 只是让函数内的 m 指向了一张新的哈希表
外部的 m 从头到尾都没有被重新赋值

这个行为，和 slice 在函数中 append 触发扩容时，其实非常相似。

它们的共同点在于：函数能修改“被指向的内容”，但不能替换“调用方持有的那个引用”。

从这个角度看，map 在函数间传递的规则其实非常一致：

修改 key-value → 对外可见
重新分配 map → 只影响函数内部

所以，如果函数的目标是“往已有 map 里填数据”，直接传 map 就足够；但如果函数的目标是“构造一个新的 map 并交给外部使用”，那就应该：

返回这个 map
或者使用 *map（但这在实践中很少推荐）

23. map 并发读写为什么会直接 panic

当前问题存在示例代码，可以前往GitHub查看

在使用 map 的过程中，有一个现象往往会让人印象很深：并发读写 map，不是数据错乱，而是直接 panic。

比如这样的代码：

m := make(map[string]int)

go func() {
	m["a"] = 1
}()

go func() {
	_ = m["a"]
}()

在很多语言里，这种情况可能只是读到不一致的数据；

但在 Go 里，它很可能直接触发运行时 panic。

一开始很容易把这个现象理解为：“Go 对 map 太严格了。”

但如果结合 map 的实现方式来看，这个选择其实非常理性。

map 底层是一张哈希表，而哈希表在写入过程中，并不是一个“稳定结构”。

一次写操作，背后可能发生的事情包括：

新 key 插入到 bucket
bucket 内元素移动
冲突链的调整
甚至触发扩容和 rehash

这些操作过程中，map 的内部状态会短暂地处于“中间态”。

如果在这个时候，另一个 goroutine 进来读：

它可能读到一个尚未完成调整的 bucket
也可能遍历到一半被修改的数据结构
最坏的情况，是破坏运行时对 map 结构完整性的假设

相比之下，Go 选择了一种非常直接的处理方式：一旦检测到并发读写，就直接终止程序。

这里的 panic，并不是为了“保护数据正确性”，而是为了保护运行时本身不进入不可恢复的状态。

换句话说，这并不是一个“业务级错误”，而是一个内存安全层面的防线。

从这个角度再看，就会发现：

map 并发读写之所以 panic
不是因为写得不安全
而是因为这种行为在语义上根本没有被定义

Go 并没有试图为 map 提供“模糊但能跑”的并发语义，而是明确要求：并发访问必须由使用者来同步。

这也和前面提到的设计取向是一致的：

map 优先追求单线程下的性能和简洁
并发语义通过 mutex、channel 或更高层抽象来解决

24. 使用 map 时的防御性写法

当前问题存在示例代码，可以前往GitHub查看

在理解了 map 的行为之后，再回头看“防御性写法”，它并不是为了让代码更复杂，而是为了减少对隐含前提的依赖。

最基础的一点，是对初始化状态保持明确。

如果一个 map 在某个路径下可能会被写，那就尽量保证它在写之前已经完成初始化：

if m == nil {
	m = make(map[string]int)
}
m["a"] = 1

这种写法本身并不优雅，但它明确地消除了 nil map 带来的不确定性。

在函数边界上，态度也可以更直接一些：

如果函数的职责是“往 map 里填数据”，那就默认调用方已经完成初始化；
如果函数需要“创建并返回一个 map”，那就直接返回，而不是试图在参数上隐式修改：

func build() map[string]int {
	m := make(map[string]int)
	m["a"] = 1
	return m
}

这样，map 的生命周期和所有权就非常清晰。

在并发场景下，防御性写法反而更简单，也更严格：

不要假设 map 在并发下“碰巧没问题”
只要存在并发写，就必须有同步
如果无法保证同步，就不要共享 map

最常见的方式，仍然是在外层使用 mutex，把所有访问收拢到同一个临界区：

mu.Lock()
m["a"] = 1
mu.Unlock()

或者，在设计上直接避免 map 成为共享状态，比如：

每个 goroutine 持有自己的 map
通过 channel 汇总结果
或者在单个 goroutine 中集中处理 map

还有一个容易被忽略的点，是对 map 行为“不过度推断”。

比如：

不依赖遍历顺序
不假设写入是原子的
不在并发场景下混用读写而不加锁

这些并不是 map 的“坑”，而是它明确不提供的保证。

把这些原则放在一起看，会发现所谓的防御性，其实只是承认一件事：map 是一个高效、直接，但边界非常清晰的数据结构。

只要不越过这些边界，它的行为就始终是稳定、可预期的。

六、defer 与资源生命周期

25. defer 的执行时机与栈模型

当前问题存在示例代码，可以前往GitHub查看

第一次看到 defer 的时候，其实很容易把它理解成一种“语法级的 finally”。

它的用途也确实很直观：在函数里声明一段逻辑，但不立刻执行，而是等当前函数结束时再处理，常见的场景就是关闭文件、释放锁、回收连接之类的资源。

f, _ := os.Open("test.txt")
defer f.Close()

// 这里做一些读写操作

如果只停留在这个层面，defer 用起来几乎没有心理负担，甚至可以完全凭直觉去用：反正函数退出时它一定会执行。

但当我继续往下看 defer 的执行规则时，发现 Go 对它的定义，其实比“函数结束时执行”要精确得多。

在 Go 里，每一次执行到 defer 语句，都会立刻发生一件事：对应的函数调用会被压入当前函数的一个 defer 栈中。

这里有几个细节是需要刻意注意的：

是绑定在当前函数上的
使用的是栈结构
压栈行为发生在 执行到 defer 那一行的当下

真正的执行，只会发生在当前函数即将返回的时候，而且顺序是后进先出（LIFO） 。

func demo() {
	defer fmt.Println("A")
	defer fmt.Println("B")
	defer fmt.Println("C")
}

这个函数返回时的输出顺序是：

C
B
A

并不是因为 Go 在“倒序执行 defer”，而是因为它从一开始就把 defer 当成一个栈来管理。

理解这一点之后，我对 defer 的认知开始发生变化：它并不是简单地“延后执行一段代码”，而是提前登记一次调用，等待合适的时机统一执行。

这一点在参数绑定上体现得尤其明显。

func demo() {
	x := 10
	defer fmt.Println(x)
	x = 20
}

最终输出的是 10，而不是 20。

原因并不复杂：在执行到 defer fmt.Println(x) 这一行时，fmt.Println(x) 这次调用就已经完整地被记录进 defer 栈了，x 的值也在这一刻被确定下来，只是执行被延后了而已。

所以从 defer 的角度看，更接近这样的模型：

现在把这次调用压栈
将来在函数返回时按顺序执行

而不是：

先记住一段代码
等函数结束时再“重新执行一次当时的上下文”

站在 PHP 的经验上看，很容易默认一种资源生命周期模型：作用域结束、对象析构、资源被自动回收。

而 defer 给出的，是一种更显式、也更可控的方式：

它不依赖 GC 的触发时机，也不依赖对象何时被销毁，而是由开发者明确地指定：这个函数结束时，我要做哪几件事。

26. defer + loop 的经典坑

当前问题存在示例代码，可以前往GitHub查看

在前面已经理解了 defer 是一个「在函数返回时统一出栈执行」的栈模型之后，再来看 defer 和 for 循环放在一起的场景，其实有必要再把逻辑拆得更细一点。

先看这样一段代码：

var i int
for i = 0; i < 3; i++ {
	defer fmt.Println(i)
}

这里很容易把注意力放在「循环」和「后进先出」上，但如果只盯着顺序，其实反而会忽略真正关键的地方。

这段代码的最终输出是：

2
1
0

这个结果本身并不反直觉，也没有什么“坑”。

原因在于：defer 在入栈时，就已经把这一次函数调用所需的一切都确定下来了。

对于 defer fmt.Println(i) 来说：

fmt.Println 是明确的函数
i 是它的参数
参数在 defer 发生的那一刻就会被求值并拷贝

所以循环过程中实际发生的是：

第一次循环：defer fmt.Println(0)
第二次循环：defer fmt.Println(1)
第三次循环：defer fmt.Println(2)

函数返回时，按后进先出的顺序执行，得到 2 1 0，这一点和前面对 defer 栈模型的理解是完全一致的。

真正容易产生误解的，其实是另一种写法：

var i int
for i = 0; i < 3; i++ {
	defer func() {
		fmt.Println(i)
	}()
}

这段代码的输出是：

3
3
3

如果只从“defer 是栈”来理解，这个结果就会显得有些突兀。但问题并不在 defer，而在于这里 defer 的到底是什么。

这一次，defer 的不是一个「已经绑定好参数的函数调用」，而是一个匿名函数本身。

这个匿名函数：

func() {
	fmt.Println(i)
}

并没有参数，i 来自外部作用域，是被闭包捕获的变量。

而在 for i := 0; i < 3; i++ 这个循环里，i 自始至终只有一个变量实例，每一轮只是不断修改它的值。

于是整个过程变成了：

循环中三次 defer，把三个“函数”压入栈中
这三个函数内部引用的，都是同一个 i
等函数真正开始执行时，循环早已结束
此时 i == 3

因此，无论出栈顺序如何，这三个 defer 最终看到的，都是同一个已经变成 3 的 i，结果自然就是 3 3 3。

这里的问题，不是执行顺序，而是变量绑定的时机。

如果希望在 defer 入栈时，就把「当时那一轮的值」固定下来，那么就需要显式地把它变成函数参数：

var i int
for i = 0; i < 3; i++ {
	defer func(n int) {
		fmt.Println(n)
	}(i)
}

在这个版本里：

每一轮循环都会创建一次新的函数调用
当前的 i 会被拷贝一份，作为参数 n 传入
defer 入栈的，是三次「参数已经确定好的调用」

于是 defer 栈中的内容等价于：

fmt.Println(0)
fmt.Println(1)
fmt.Println(2)

函数返回时按后进先出执行，最终输出：

2
1
0

从这个角度再回头看，「defer + loop 的坑」其实并不是一个独立的规则，而是：

defer 是否在入栈时绑定了参数
闭包是否捕获了外部变量
循环变量在作用域内是否只有一个实例

这几个语言层面的行为，在同一个场景里同时出现时，被集中地暴露了出来。

而 defer，只是让这个问题变得更容易被注意到而已。

27. defer 在 Web 请求中的正确使用方式

当前问题存在示例代码，可以前往GitHub查看

把 defer 放进 Web 请求里，其实一开始是很自然的一件事。

在一个 HTTP handler 里，生命周期本身就非常清晰：一次请求进来，函数被调用；请求处理完成，函数返回。

func handler(w http.ResponseWriter, r *http.Request) {
	conn := getConn()
	defer conn.Close()

	// 使用 conn 处理请求
}

从 defer 的模型来看，这段代码几乎是“教科书级别地正确”：资源在函数中创建，在函数返回时释放，请求的生命周期和资源的生命周期是对齐的。

问题并不出在这种写法上，而是出在：什么时候，defer 不再和一次请求的生命周期一一对应。

一个很容易被忽略的前提是：defer 只和当前函数的返回绑定，而和 HTTP 请求“本身”没有任何直接关系。

只要函数没有返回，defer 就不会执行。

这在大多数同步处理的 handler 里不是问题，但一旦请求处理中出现了下面几种情况，直觉就很容易失效：

handler 内部启动了 goroutine
资源被传递给了异步逻辑
函数提前返回，但逻辑仍在继续执行

比如这样一种写法：

func handler(w http.ResponseWriter, r *http.Request) {
	conn := getConn()
	defer conn.Close()

	go func() {
		// 使用 conn 做一些异步处理
		doSomething(conn)
	}()

	w.WriteHeader(http.StatusOK)
}

从代码表面看，defer 依然存在，conn.Close() 也依然会被调用。

但从生命周期的角度看，这里的资源已经脱离了请求处理函数的控制范围。

handler 一返回，defer 立刻执行，而 goroutine 里的逻辑，可能才刚刚开始。

在这种情况下，defer 并没有“失效”，失效的是把资源生命周期继续托付给当前函数这个假设。

这也是我在 Web 场景下重新理解 defer 的一个关键点：

defer 只能管理“严格属于当前函数”的资源生命周期。

一旦资源被交给了其他 goroutine、其他组件，那它的释放时机，就不应该再由当前函数的 defer 来决定。

如果资源确实需要跨 goroutine 使用，那么就必须显式地把生命周期管理也一并交出去，比如：

由启动 goroutine 的那一方负责 Close
或者在 goroutine 内部使用 defer
或者通过 channel / context 明确结束信号

另一个常见但更隐蔽的问题，是把 defer 放在过大的函数作用域里。

在 Web 服务中，一个 handler 往往不仅仅是“处理请求”，而是串联了：

参数解析
权限校验
数据库操作
外部服务调用
响应构造

如果所有资源都在函数一开始创建，然后统一 defer 到函数结束才释放，从语义上看没问题，但从资源占用的角度看，生命周期可能被无意义地拉长了。

func handler(w http.ResponseWriter, r *http.Request) {
	db := getDB()
	defer db.Close()

	// 前面一大段并不需要 db 的逻辑
	validate(r)
	parseParams(r)

	// 很后面才真正使用 db
	query(db)
}

这里 defer 的行为依然是完全正确的，但它也在提醒我：defer 不会帮你缩短生命周期，它只会忠实地等到函数返回。

如果希望资源“用完就释放”，那就要么缩小作用域，要么主动拆分函数。

所以在 Web 请求中，我后来给自己立了一条非常朴素的使用准则：

如果资源的生命周期 === 当前 handler 函数 → 用 defer，毫不犹豫
如果资源会被异步逻辑继续使用 → 不要在 handler 里 defer
如果资源只在函数中间一小段逻辑里有效 → 缩小作用域，而不是指望 defer 足够聪明

从这个角度看，defer 在 Web 场景下并不是“好不好用”的问题，而是你有没有把函数边界当成资源生命周期边界的问题。

而这恰好也是 Go 在很多地方反复强调的一件事：生命周期是显式的，责任是清晰的。

28. Go 中资源释放为什么必须显式

当前问题存在示例代码，可以前往GitHub查看

在把 defer 放进 Web 请求的语境里之后，我慢慢意识到一个问题：Go 里几乎所有重要的资源释放，都是显式的。

文件要手动 Close()，数据库连接要手动 Close()，锁要手动 Unlock()，

哪怕有 GC，这些事情也都不会被自动完成。

一开始很容易把这个现象理解成：Go 比较“底层”，或者“对开发者不够友好”。

但当我把 defer、函数生命周期、Web 请求这些东西放在一起之后，才发现这并不是能力不足，而是一个非常明确的取舍。

在 Go 里，GC 负责的事情其实被刻意限制得很窄：它只负责内存，不负责语义层面的资源。

内存的回收，本质上是“对象是否还能被访问”的问题；

而文件、连接、锁这类资源，是否应该被释放，往往并不是一个“是否还被引用”就能决定的事情。

以数据库连接为例：

连接对象还在被某个结构体持有
但从业务语义上，这个请求已经结束
这个连接其实已经“应该被归还”了

GC 并不知道这些语义，也不应该知道。

如果把资源释放的责任交给 GC，那么释放时机就会变成一种不可预测的副作用，而不是程序行为的一部分。

站在 PHP 的经验上，这种差异尤其明显。

很多时候，我们并没有显式地关闭连接、文件或者句柄，因为：

请求结束
进程模型或 SAPI 回收资源
脚本生命周期天然兜底

这些机制并不是不存在，只是它们发生在语言之外，而不是语言本身的语义里。

而 Go 的运行模型是长期运行的进程、并发的 goroutine、复用的资源池。

在这种模型下，如果资源释放是“顺便发生的”，那么问题就会变得非常难以定位。

这也是为什么 Go 选择了这样一种看起来有点“冷静”的方式：

资源的获取是显式的
资源的释放也是显式的
生命周期绑定在函数边界上
释放时机由开发者明确声明

defer 在这里并不是为了“帮你自动释放资源”，而是为了让你在逻辑上把释放这件事写在最合适的位置，而执行时机又足够可靠。

从这个角度看，defer 更像是一种结构化承诺：

我在这里获取了资源我已经在同一个函数里声明了它的结束方式

当我把“显式释放”这件事和 Web 请求重新对齐之后，这个选择就变得非常合理了。

一次请求：

什么时候开始
什么时候结束
用了哪些资源
在哪里释放

这些信息都应该是从代码结构上就能读出来的，而不是依赖运行时的某个隐含行为。

这也是为什么在 Go 里，很多看起来有点“啰嗦”的写法，其实是在换取一件事：资源生命周期是可推导的。

七、error：Go 的“显式异常系统”

29. error 是值，而不是异常

当前问题存在示例代码，可以前往GitHub查看

在刚接触 Go 的时候，我对 error 这个东西的第一反应，其实还是把它往「异常」上靠。名字叫 error，看起来又无处不在，很难不联想到 PHP 里的 Exception。

但真正开始写代码之后，会发现 Go 的 error 从一开始就被设计成了一种非常普通的存在。

它不是关键字，也不是语法结构，只是一个接口：

type error interface {
    Error() string
}

这行定义本身就已经说明了很多问题。error 并没有什么“特殊能力”，它既不能中断程序执行，也不能改变控制流。

它唯一能做的事情，就是通过 Error() 方法提供一段错误信息。

在使用层面上，error 通常会和函数返回值一起出现：

result, err := doSomething()

这在 Go 里几乎是最常见的函数签名模式之一。函数要么返回一个有效结果，要么返回一个非 nil 的 error，调用方拿到这两个值之后，再决定接下来该怎么走。

这个时候，如果还是用 PHP 的异常模型去理解，就会有一种明显的不适感。

在 PHP 里，一旦抛出异常，代码的执行路径会立刻发生变化。

当前函数后面的逻辑不再执行，调用栈自动回退，直到遇到 catch。

你不需要在每一层显式地处理它，语言会帮你把异常“抛”到一个合适的位置。

而 Go 刻意没有提供这种能力。

在 Go 里，错误本身不具备“跳出去”的权力。函数返回了一个 error 之后，程序依然沿着原来的路径往下执行，除非你显式地做出选择。

v, err := doSomething()
// 这里不会自动发生任何事

你可以检查它，也可以忽略它，甚至可以什么都不做。语言层面不会替你判断“这个错误到底严不严重”。

慢慢接受这一点之后，我开始意识到：在 Go 的设计里，error 更像是函数结果的一部分，而不是“异常情况”。

从这个角度看，很多事情就变得更好理解了。

在 PHP 里，我们其实也经常会遇到类似的情况，只是表达方式不同。比如：

返回 false 或 null，再由调用方判断
返回一个包含 success / error 字段的结构
或者直接抛异常，把处理权交给外层

Go 只是把这种「成功 / 失败」的状态显式地放进了函数签名里，而且用的是类型系统，而不是控制流。

这也解释了为什么 Go 社区里经常会强调一句话：错误是值（error is a value） 。

它的含义并不是“错误不重要”，而是恰恰相反——错误是一个需要被看见、被传递、被讨论的结果，而不是一个被语言机制悄悄带走的分支。

当我把 error 当成值来看待，而不是异常时，心态上会发生一个很微妙的变化。关注点不再是「这里会不会 throw」，而是：

这个函数在失败时，会返回什么信息
我在这一层，是否真的有能力处理这个错误
如果处理不了，我该原样返回，还是补充一些上下文

所以说：Go 并不是“没有异常”，而是根本不打算用异常来解决错误处理这件事。

30. `if err != nil` 为什么是设计选择

当前问题存在示例代码，可以前往GitHub查看

顺着前面对 error 的理解，if err != nil 这件事其实就不再是一个语法问题，而是一个非常明确的设计态度。

一开始写 Go 的时候，我对这一行是有点抗拒的。几乎每调用一次函数，就要紧跟着写一行 if err != nil，代码看起来重复，又不够“优雅”。

从 PHP 的视角看，这些本来是可以被 try / catch 包起来、一次性处理掉的东西。

但后来我慢慢意识到，这种“重复”，并不是 Go 没能力抽象，而是刻意不帮你抽象掉。

如果错误是值，那么它就必须像其他返回值一样，被显式地检查。if err != nil 本质上是在逼你在这一行代码上做出一个决定：你到底认不认这个错误的存在。

v, err := doSomething()
if err != nil {
    return err
}

这一段代码看起来很机械，但它有一个非常直接的效果：在阅读代码的时候，我不用去脑补“这里可能会抛异常”，也不用在脑海里维护一条隐形的异常路径。错误处理和正常逻辑，是在同一个时间、同一个位置被展开的。

这和异常模型的一个核心差异在于：异常往往是延迟理解的。你在读当前函数的时候，很难立刻知道：

哪些函数可能抛异常
这个异常会被谁接住
中间有没有被吞掉或转换

而 if err != nil 是即时可见的。

错误有没有被处理、是被忽略、被记录，还是被直接向上返回，全部都写在当前函数里。

从这个角度看，Go 并不是在追求“少写代码”，而是在追求一种更低的认知负担。它把复杂度摊开了，而不是藏起来。

另外一个让我逐渐接受这个设计的点，是它对“层级责任”的划分非常清晰。

在 PHP 里，用异常很容易不自觉地写出一种代码结构：底层随意 throw，上层统一 catch。

这在很多时候是合理的，但也很容易演变成“所有错误都在最外层兜底”，中间层反而对错误语义变得模糊。

而在 Go 里，每一层都要直面 err，你必须在这一层明确回答一个问题：

这个错误我能处理吗？
如果不能，我是否要补充信息再往上抛？
还是应该在这里转成另一个错误？

if err != nil 的重复，其实是在不断提醒你：错误处理是业务逻辑的一部分，而不是附加逻辑。

甚至从代码结构上看，这种写法也在引导一种固定的节奏：先处理错误，再处理正常路径。很多 Go 代码都会把错误判断放在函数前半段，形成一种“早返回”的形态。

if err != nil {
    return err
}

// 后面可以默认假设一切正常

这种结构让正常逻辑尽量少嵌套，也减少了在脑子里同时维护多种执行分支的负担。

所以后来再回头看，if err != nil 并不是 Go 没有更“高级”的错误机制，而是它选择了一种最直白、最难被忽略的方式。

它牺牲的是代码的简洁感，换来的是错误处理的可见性和确定性。

31. 错误向上传递的最佳实践

当前问题存在示例代码，可以前往GitHub查看

在接受了 error 是值、if err != nil 是一种刻意设计之后，下一个绕不开的问题其实是：那这些错误到底应该怎么往上交？

刚开始写 Go 的时候，我对“向上传递”这件事的理解其实非常简单，甚至有点机械：底层返回 err，中间层原样 return err，最外层统一处理。

if err != nil {
    return err
}

这当然是对的，但写多了之后，会发现一个问题：错误虽然被传上去了，但信息并没有一起传上去。

等错误真的冒到最外层时，往往只剩下一句很底层、很抽象的描述，比如“not found”“invalid argument”。

这时候再回头看调用链，反而要花时间去猜：这个错误是在哪一层发生的？当时在做什么？

后来我慢慢意识到，Go 里所谓的“向上传递”，并不是单纯的“往上扔”，而是一个逐层补充语义的过程。

一个比较稳定的判断标准是：这一层如果无法处理错误，那它至少应该让错误在离开这一层之前，变得更好理解。

最常见、也最安全的做法，其实是“原样返回 + 补充上下文”。

if err != nil {
    return fmt.Errorf("load user config failed: %w", err)
}

这里做的事情并不复杂，只是把“当前这层在做什么”这件事，和原始错误绑在了一起。

等错误真的被打印或记录时，调用路径会自然地浮现出来。

相反，有几种做法在一开始我也写过，但后来会尽量避免。

比如在中间层直接“吃掉”错误，只返回一个新的、看起来更抽象的错误：

return errors.New("something went wrong")

这样写虽然干净，但实际上切断了错误的来源。

一旦线上出问题，除了复现，很难再靠错误本身定位。

另一种极端，是在每一层都急着“处理”错误，比如打印日志、统计、甚至直接 panic。

这会导致一个结果：同一个错误在不同层被反复处理，责任边界变得模糊。

慢慢地我给自己形成了一个比较清晰的分工习惯：

底层：负责返回“事实性的错误”，尽量准确描述发生了什么
中间层：如果处理不了，就补充“语境”，再向上返回
顶层 / 边界层：决定如何对外呈现（日志、返回值、HTTP 状态码等）

在这个结构下，“向上传递”不再是消极的甩锅，而是一种有意识的协作。

还有一个对我帮助很大的点，是尽量避免用错误来承载“流程控制”。

比如把“查不到数据”当成异常错误一路往上抛，最后在最外层再去判断。这在 Go 里通常会让代码读起来很拧巴。

更自然的方式，反而是让函数签名本身表达清楚语义，比如：

user, err := findUser(id)
if err != nil {
    return nil, err
}
if user == nil {
    // 这是业务分支，而不是系统错误
}

当错误只用于“真正的失败情况”，而不是“常见分支”，向上传递这件事才不会变形。

写到这里我才发现，Go 对错误向上传递的“最佳实践”，并没有什么神秘技巧。

它只是反复在提醒你：错误不是用来丢掉的，也不是用来滥用的，而是用来逐层说明发生了什么。

32. panic、recover 的合理使用场景

当前问题存在示例代码，可以前往GitHub查看

在理解了 Go 日常错误处理的方式之后，panic 和 recover 反而会显得有点“格格不入”。

一边是被反复强调的 error、if err != nil、向上传递，另一边却突然冒出来一套看起来很像异常的机制，很容易让人产生一个误解：那我是不是也可以把 panic 当异常用？

至少对我来说，这是一个需要刻意纠正的想法。

从行为上看，panic 确实会中断当前执行流程，开始回退调用栈，如果没人 recover，程序就直接崩掉。

这一点和 PHP 里的异常非常像。但差别在于，Go 并没有把它设计成“日常错误处理”的一部分。

更准确地说，panic 面向的不是“失败的业务情况”，而是：程序已经进入了不该存在的状态。

这也是我后来判断要不要用 panic 的一个核心标准：这个错误是不是意味着程序的假设已经被打破了？

比如：

明明已经校验过的数据，却出现了不可能的值
内部逻辑出现了明显的程序错误
初始化阶段的关键配置缺失，程序根本不可能继续跑

在这些场景里，继续返回 error 往上交，反而会让代码变得很奇怪。

因为调用方即使“收到了错误”，也并没有什么合理的补救方式。

if cfg == nil {
    panic("config must not be nil")
}

这种 panic 本质上是在说：

不是你用错了这个函数，而是我这个程序已经写错了。

recover 的存在，反而是为了让 panic 不至于把一切都拉着一起死。

但它的使用场景，其实比我一开始想象的要窄得多。

recover 只能在 defer 里生效，这本身就已经在限制它的使用方式了。

它并不是让你在任何地方随意“抓 panic”，而更像是一种边界保护机制。

一个我后来觉得比较合理的使用位置，通常是在“最外层边界”：

HTTP 服务的请求入口
goroutine 的启动封装
框架级的调度入口

在这些地方，用 recover 做一层兜底，可以防止单个请求或任务因为 panic 把整个进程带崩。

defer func() {
    if r := recover(); r != nil {
        // 记录日志，返回 500
    }
}()

这里的目标并不是“把 panic 转成普通错误继续用”，而是：

记录足够的信息
保证系统还能继续服务
给开发者一个明确的信号：这里发生了不该发生的事

我后来会尽量避免在业务逻辑中显式调用 recover。

一旦在中间层开始捕获 panic，就很容易把程序错误伪装成业务错误，反而延迟问题暴露。

所以在 Go 里，panic / recover 更像是一条安全网，而不是一条“备用错误通道”。

它存在的意义，不是为了替代 error，而是为了应对那些本不该出现、却一旦出现就必须被立刻注意到的问题。

把它们放在这个位置上看待时，就不会再纠结“什么时候该用 panic，什么时候该用 error”这种二选一的问题了。

绝大多数情况下，错误都只是错误；而只有在极少数情况下，才是 panic。

33. 错误包装（wrap）与错误定位

当前问题存在示例代码，可以前往GitHub查看

在错误一路向上传递的过程中，有一个问题其实迟早会碰到：当错误真的被打出来的时候，我还能不能看懂它是从哪来的？

如果只是简单地 return err，那错误当然是完整的，但它通常只包含最底层的一小段信息。

如果每一层都重新 errors.New 一次，错误看起来倒是“干净”了，却完全失去了来源。

错误包装（wrap）这件事，正好卡在这两者之间。

Go 在 1.13 之后，把这件事变成了一种正式的、被语言支持的模式。最直观的体现，就是 %w 这个占位符。

if err != nil {
    return fmt.Errorf("open config file failed: %w", err)
}

这行代码表面上只是拼了一段字符串，但语义上发生了一件很关键的事：新的错误并没有覆盖旧的错误，而是把它包了进去。

于是错误开始有了“层级”。

当错误一路往上传的时候，每一层都只做一件很小的事：补一句「我当时在干什么」。

等这个错误最终被打印出来时，你往往能看到一条非常符合调用顺序的描述链。

这种感觉和异常的 stack trace 有点像，但它是显式构建出来的，而不是运行时偷偷帮你收集的。

更重要的是，包装并不只是为了“好看”。

一旦错误是通过 %w 包起来的，它在语义上仍然是“原来的那个错误”。

这意味着你在上层依然可以判断错误的本质，而不是被字符串绑死。

if errors.Is(err, fs.ErrNotExist) {
    // 文件不存在
}

哪怕这个错误已经被包了好几层，只要中间没有被打断，errors.Is 都还能沿着错误链往里找。

这点对我来说是一个很大的转变。

在 PHP 里，异常的类型判断往往依赖 class 继承关系；而在 Go 里，错误定位更多是通过“语义关系”而不是“类型层级”。

同样的，还有 errors.As，可以用来判断错误链中是否存在某一类错误，并把它取出来。

var pathErr *fs.PathError
if errors.As(err, &pathErr) {
    // 可以访问更具体的错误信息
}

到这里我才意识到，Go 的错误包装并不是在补一个“异常系统”，而是在构建一条可追溯、可判断、可组合的错误链。

当然，这里也有一些很容易踩的点。

比如在中间层用 fmt.Errorf，却忘了用 %w，而是直接 %v 或字符串拼接。

这样一来，错误在这一层就被“截断”了，上层再也无法判断它的真实来源。

还有一种情况，是过度包装。每一层都加一大段说明，最终的错误信息反而变得冗长、重复，失去了重点。

我后来比较倾向的做法是：只在“语义发生变化”的地方包装错误。

从 IO 层进入业务层
从业务层进入接口层
从内部模块进入对外边界

这些地方的错误含义，对上层来说确实发生了变化，加一层上下文是有价值的。

等把这一整套连起来再回头看，会发现 Go 在错误处理上的态度其实一直很一致：不自动做决定、不隐藏信息，也不强迫你遵循某种宏大的模式。

它只是给了你一些很基础的工具，然后把“错误该长成什么样子”的责任，交还给了代码本身。

八、Go 的并发模型：从根上和 PHP 不一样

34. goroutine 不是线程

当前问题存在示例代码，可以前往GitHub查看

刚接触 goroutine 的时候，我几乎是本能地把它理解成「更轻量的线程」。这种理解在一开始并不会立刻出问题，但它会在后面不断制造偏差。

后来我意识到，问题并不在于“轻不轻”，而在于 goroutine 根本就不是线程。

在 PHP 的世界里，并发通常意味着直接使用操作系统提供的能力：多进程，或者线程。

这些并发单元本身就是 OS 资源，创建和切换都发生在内核态，对应的是清晰、可感知的成本。

所以不管是 PHP-FPM 的 worker，还是显式的线程模型，本质上都在和操作系统打交道。

而 goroutine 完全不在这个层面。

它并不是操作系统的执行单元，而是 由 Go runtime 管理的一段执行逻辑。

操作系统只看到少量线程在运行 Go 程序，但这些线程内部真正被调度、被切换的，其实是一批 goroutine。

至于某个 goroutine 此刻跑在哪个线程上，操作系统并不知道，Go 程序本身也不需要知道。

这一点会直接改变对并发的直觉。

在 OS 线程模型下，一个线程通常意味着：

一个固定大小的栈（往往是 MB 级别）
创建和销毁需要内核参与
上下文切换成本不可忽略

而 goroutine 的特性更像是：

初始栈非常小（只在需要时才增长）
调度和切换发生在用户态
不和某个线程绑定，可以被 runtime 迁移

所以，把 goroutine 理解成「轻量线程」其实是不够准确的。

更贴切的说法是：它是 Go 语言层面提供的一种并发执行结构，而不是系统层面的执行单元。

如果强行用 PHP 的经验去类比，线程更像是一个 PHP-FPM worker，而 goroutine 更像是 worker 里的某一段执行流。

这个类比只能帮助理解“为什么数量可以很多”，却不能用来解释行为差异。

因为在 PHP 里，请求和执行上下文的关系是稳定的；

而在 Go 里，goroutine 只是 runtime 调度的对象，它随时可能被挂起、恢复，甚至换一个线程继续跑。

这也是一个很重要的认知转折点：

Go 并不是在“更高效地使用线程”，而是 把并发这件事从操作系统层面，收回到了运行时和语言层面。

一旦接受了这个前提，后面再去看调度模型、channel 这些设计，就不太容易陷入“它为什么要这么复杂”的困惑，而更像是在理解一套自洽的取舍。

35. GMP 调度模型的直觉理解

当前问题存在示例代码，可以前往GitHub查看

既然 goroutine 不是线程，那一个很自然的问题就会冒出来：这些 goroutine 到底是靠什么在跑？

答案其实不复杂，但一开始很容易被名词带偏。

Go 运行时真正关心的，其实只有三样东西：要跑的任务、真正能跑代码的执行单元、以及把两者对接起来的调度机制。GMP 模型就是围绕这三件事展开的。

在这个模型里，G（goroutine）本身只是“一段可以被执行的逻辑”，它不具备执行能力；

M（machine）才是真正对应操作系统线程的东西，负责执行代码；

而中间那个 P（processor），一开始看起来最抽象，但它恰恰是整个模型成立的关键。

如果把这三者放在一起看，会发现它们的分工非常克制：

G：我要跑的代码
M：真正跑代码的 OS 线程
P：调度和执行所需的“运行环境”

真正让我想通的一点是：goroutine 不能直接被线程执行，中间必须经过 P。

没有 P，M 就算是空闲的，也不能随便去跑一个 G。

P 可以理解成一种“执行许可”。

一个 M 想执行 Go 代码，必须先拿到一个 P；而一个 P 在同一时刻，只会被一个 M 持有。于是就形成了一个非常重要的约束：同一时间真正并行执行 Go 代码的数量，等于 P 的数量。

这时候再回头看 GOMAXPROCS，就会发现它不是在控制线程数，而是在控制 P 的数量。

换句话说，它限制的是“允许多少个 goroutine 同时在跑”，而不是“起多少个线程”。

这种多绕一层的设计，一开始确实不直观，但它解决了一个在 PHP 或传统线程模型里很难优雅处理的问题：调度的可控性。

如果只有 goroutine 和线程，那么要么 goroutine 直接绑定线程，要么线程自己去抢任务，这两种方式都会让调度策略被 OS 主导。

而引入 P 之后，Go runtime 就把调度的主动权牢牢握在自己手里。goroutine 的切换、暂停、恢复，甚至迁移到另一个线程，都可以在用户态完成。

从直觉上看，可以这样理解这套关系：

G 决定“要不要跑”
P 决定“现在能不能跑”
M 负责“真正去跑”

当一个 goroutine 因为 I/O、系统调用或者 channel 操作被阻塞时，Go runtime 并不会傻等着那个线程回来，而是可以把 P 从这个 M 手里拿走，交给另一个空闲的 M，继续跑其他 goroutine。

被阻塞的那个 goroutine，等条件满足后，再重新进入调度队列。

这一点对我冲击很大，因为它和 PHP 的并发直觉几乎是反着来的。

在 PHP 里，一个请求一旦进入阻塞状态，这个执行单元基本就被“占住”了；

而在 Go 里，阻塞的是 goroutine，而不是承载它的线程。

所以，GMP 模型并不是为了炫技而复杂，而是为了让 goroutine 这种“不绑定线程的执行单元”真正可行。

它通过在中间加一个 P，把“并发结构”和“系统资源”彻底解耦了。

当我把这一层关系想清楚之后，很多之前看起来“有点魔法”的行为，其实就变得很朴素了：为什么 goroutine 可以大量创建，为什么阻塞 I/O 不一定拖慢整个程序，也为什么 Go 的并发更像是一种语言级能力，而不是系统能力的简单封装。

36. 为什么 Go 可以“随便起协程”

当前问题存在示例代码，可以前往GitHub查看

在理解了 goroutine 不等于线程、以及 GMP 是怎么把执行和调度拆开的之后，再回头看「Go 可以随便起协程」这件事，就不太容易走偏了。

这里的“随便”，并不是没有代价，而是 代价不在你原来以为的地方。

如果我还停留在“一个并发单元≈一个线程”的直觉里，那“起很多 goroutine”听起来几乎就是在自杀式地消耗资源。

但实际上，goroutine 的成本模型和线程完全不同。

它既不直接占用一个 OS 线程，也不一开始就分配一大块固定栈空间，它更像是 Go runtime 里的一条“待执行任务记录”。

直观一点看，一个 goroutine 至少包含的东西其实非常有限：执行函数、当前的栈信息、以及一些调度相关的元数据。栈本身还是按需增长的。

这意味着，起一个 goroutine 的成本，更接近一次函数调用的延伸，而不是一次线程创建。

这也是为什么在 Go 里，经常能看到这样的代码，而不需要太多心理负担：

go handleConn(conn)

如果把这行代码放到 PHP 或传统线程模型里去理解，那几乎是在“每来一个连接就开一个线程”。

但在 Go 里，这更像是告诉 runtime：这里有一段逻辑，可以并发地跑，至于什么时候跑、在哪跑、要不要暂时停一停，不是我现在关心的事情。

真正限制 goroutine 并发规模的，并不是它们的数量，而是 P 的数量，以及底层资源是否会成为瓶颈。

也就是说，你可以创建很多 goroutine，但真正同时在执行的，永远只有那么几个，剩下的只是排队等待调度。

这一点和 PHP 的直觉差异很大。

在 PHP 里，创建并发执行单元本身就是一件需要谨慎对待的事，因为它几乎等同于消耗真实的系统资源；

而在 Go 里，创建 goroutine 更多是在描述并发结构，而不是立刻兑现资源。

换个角度看，Go 鼓励“随便起协程”，其实是在鼓励你把并发当成程序结构的一部分来写，而不是把它当成一种昂贵的优化手段。

你先把逻辑拆清楚，哪些事情可以并行，哪些地方需要等待，runtime 再根据实际情况去做调度上的取舍。

当然，这并不意味着 goroutine 是“免费的”。

当 goroutine 数量膨胀到一定规模时，内存占用、调度开销、以及共享资源上的竞争，都会开始显现出来。

只是这些成本不再以“线程数暴涨”的方式出现，而是更隐蔽、更延后。

所以我后来对“Go 可以随便起协程”这句话的理解是：你可以大胆地创建 goroutine，因为它们不会立刻把系统拖垮；但是否真的应该这么做，取决于你对并发边界的设计。

这句话听起来像是给了你更大的自由，但实际上，它只是把“什么时候付出代价”这件事，推迟到了更接近业务逻辑和资源瓶颈的地方。

37. 并发 ≠ 更快：什么时候并发是负担

当前问题存在示例代码，可以前往GitHub查看

在理解了 goroutine 很轻、调度由 runtime 接管、并且“起很多协程”本身并不会立刻出问题之后，很容易产生一个错觉：既然如此，那并发是不是总能让程序更快？

答案显然是否定的。

并发解决的是结构问题，而不是性能保证；当问题本身并不适合并发时，并发反而会成为一种负担。

最直观的一类情况，是 CPU 资源本来就不够。

不管起多少 goroutine，真正能同时执行的数量始终受 P 的数量限制。

当所有 goroutine 做的都是纯计算时，并发只是在争抢同一批 CPU 时间片，结果往往不是更快，而是多了一层调度成本。

在这种情况下，并发带来的不是吞吐提升，而是：

更多的上下文切换
更复杂的执行路径
更难预测的性能波动

这点和 PHP 的多进程模型其实很相似，只是表现形式不同而已。

另一类更隐蔽的负担，来自 共享资源。

当多个 goroutine 需要频繁访问同一份数据、同一个锁、同一个 channel 时，并发并不会放大处理能力，反而会把瓶颈放得更明显。

你看到的并不是“同时在干活”，而是“同时在等待”。

在代码层面，这种负担往往体现为：

锁竞争导致的阻塞
channel 堵塞导致的 goroutine 堆积
goroutine 数量很多，但真正有效工作的很少

这时候并发结构越复杂，问题反而越难定位。

还有一类情况，是 并发规模和任务粒度不匹配。

如果每个 goroutine 只做一点点事情，执行时间极短，那么调度、创建、回收这些隐性的成本，就会开始占据主要比例。

并发带来的收益还没出现，开销已经先付出去了。

这也是我后来慢慢意识到的一点：goroutine 很轻，并不意味着“可以忽略它的成本”，而只是意味着 成本更分散、更不直观。

从 PHP 转到 Go 之后，一个很容易出现的误区是，把“可以随便起协程”理解成“应该尽量并发”。

但实际上，Go 的并发模型给的是表达能力，而不是性能承诺。

你可以把并发写得很自然，但是否真的要并发，依然是一个需要判断的问题。

到这里，这一章对我来说才算完整地闭环了：Go 之所以强调并发，不是因为它能自动让程序变快，而是因为它把并发变成了一种更容易表达、也更容易被 runtime 调度的程序结构。

至于性能提升与否，取决的从来都不是 goroutine 的数量，而是问题本身是否适合并发。

这也是我现在回头再看这套模型时，一个比较冷静的结论：并发不是捷径，它只是把复杂度换了一个位置。

九、channel：通信，而不是共享内存

38. channel 的设计哲学

当前问题存在示例代码，可以前往GitHub查看

第一次看到 channel 时，很容易把它当成一种语法结构：一个可以在 goroutine 之间传递数据的管道。

你往里 send 一个值，另一端 receive 到这个值，如果两边有一方没准备好，操作就会被阻塞。

ch := make(chan int)

go func() {
    ch <- 1
}()

v := <-ch

如果只停在这里，channel 看起来更像是一个“带阻塞能力的队列”。

但当我真正开始用它来组织并发逻辑时，会慢慢意识到：Go 并不是想给你一个更好用的共享容器，而是在引导你换一种并发思路。

Go 在并发模型里有一句经常被引用的话：不要通过共享内存来通信，而要通过通信来共享内存。

channel 正是这句话最直接、也最具体的体现。

从设计哲学上看，channel 有几个很明显的取向。

首先，它刻意弱化了“共享状态”这件事。

你很少会把 channel 当成一个“大家随便用的公共变量”，更常见的反而是这种结构化的用法：

谁创建 channel，谁决定它的生命周期
有些 goroutine 只负责写，有些只负责读

func producer(ch chan<- int) {
    ch <- 1
}

func consumer(ch <-chan int) {
    fmt.Println(<-ch)
}

这里甚至通过类型系统，把“你能不能写”这件事直接限制住了。

在 PHP 里，我们更多是靠约定来避免误用；而在 Go 里，channel 更像是在说：这件事我帮你从语法层面就堵死了。

其次，channel 把“同步”变成了“通信的自然结果”。

在很多并发模型中，同步是显式存在的概念：

加锁 / 解锁
等待 / 通知

而在 channel 的语义里，你往往不会单独去写“同步逻辑”：

ch <- data

这一行代码既表达了“我要传一个值”，也隐含了：在有人接收之前，这一步不会继续往下走。

同步不再是额外的控制结构，而是通信本身的一部分，这会直接改变你组织代码时的关注点。

第三，channel 明显在鼓励你先想清楚数据是如何流动的。

当我用锁来写并发代码时，脑子里更多想的是：

哪些变量是共享的
哪些地方需要加锁
锁会不会忘记释放

而当我用 channel 时，思路会自然变成：

数据从哪里产生
经过哪些 goroutine
最终由谁来消费

jobs := make(chan Job)
results := make(chan Result)

光看这些名字，就已经在描述系统的结构，而不是底层的并发细节。

所以后来我对 channel 的理解发生了一个明显的转变：它不是用来“让我不犯错”的工具，而是用来逼我把并发关系想清楚的工具。

当你觉得 channel 用起来很别扭时，很多时候并不是语法的问题，而是并发结构本身还没有想清楚。

这一点，对习惯了 PHP 那种“共享状态是默认存在的世界”的人来说，感受会尤其明显。

39. 无缓冲 channel vs 有缓冲 channel

当前问题存在示例代码，可以前往GitHub查看

刚看到无缓冲 channel 和有缓冲 channel 的时候，很容易把区别理解成一句话：一个容量是 0，一个容量大于 0。

ch1 := make(chan int)    // 无缓冲
ch2 := make(chan int, 3) // 有缓冲

但如果只停在“能不能存东西”这个层面，其实很难理解 Go 为什么要把这两种形式都作为一等公民提供出来。

无缓冲 channel 带给我的第一个强烈感受是：它不是在“存数据”，而是在强制一次同步交接。

ch := make(chan int)

go func() {
    ch <- 1
    // 这里会等待
    fmt.Println("send done")
}()

time.Sleep(time.Millisecond * 100)
fmt.Println(<-ch) // 此处输出完成后，才会输出 send done

在这里，ch <- 1 并不会因为“值已经算好了”就立刻结束。

它表达的是：我现在有一个值，只有当你准备好接收时，这一步才算完成。

后来我慢慢意识到，无缓冲 channel 更像是在建模一种关系： “你我必须在同一个时间点达成一致” 。

从这个角度看，它的语义其实非常强：

发送方知道：一定有人正在接
接收方知道：一定有人正在发
同步点被明确地放在了“数据交接”这个动作上

它并不关心吞吐量，也不关心性能优化，它关心的是并发结构是否清晰。

有缓冲 channel 则明显在表达另一种取向：发送和接收可以在一定程度上解耦。

ch := make(chan int, 2)

ch <- 1
ch <- 2
// 只有 ch 超过 2 位才会堵塞，因此会先输出 send done
fmt.Println("send done")
fmt.Println(<-ch)
fmt.Println(<-ch)

只要缓冲区还有空间，发送方就可以继续往下走，而不必等某个 goroutine 立刻来接。

这里的 channel 更像是在说：我不要求你“此刻”就处理这个值，但我保证这些值会按顺序交给你。

所以有缓冲 channel 引入的，其实不是“性能优化”这么简单，而是时间上的松弛度：

发送方可以跑得稍微快一点
接收方可以慢一点再处理
两者之间通过缓冲区形成了一个“过渡层”

但有意思的是，这两种 channel 的设计，并没有谁“更高级”。

它们关注的重点完全不同。

无缓冲 channel 更偏向于：

表达明确的同步关系
作为 goroutine 之间的“会合点”
让并发结构本身变得可读

而有缓冲 channel 更偏向于：

平衡生产和消费速度
削弱时间上的强耦合
提高系统的整体吞吐能力

我后来反而发现，一个挺实用的判断方式是：如果我一开始就知道“这里需要多大缓冲”，那往往说明我已经在考虑系统节奏了；

而如果我更关心“这两步必须严格对齐”，无缓冲 channel 通常更贴合我的直觉。

从 PHP 的视角看，这个区别也挺有意思。

无缓冲 channel 更像是一次“同步调用的拆分版本”；

而有缓冲 channel，则更接近我们熟悉的消息队列，但被压缩进了语言层面。

所以它们的差异，并不只是“能不能存几个值”，而是在表达：你到底想要的是一次强同步的交接，还是一次允许错峰的传递。

40. 谁负责关闭 channel

当前问题存在示例代码，可以前往GitHub查看

先从一个容易踩到的直觉说起。

很多人（包括我一开始）会把 close(channel) 理解成：我用完了，顺手关一下。

但 channel 并不是文件，也不是数据库连接。

它本身不占用什么稀缺资源，不关闭并不会导致泄漏。

真正会出问题的，是对已经关闭的 channel 继续发送数据。

close(ch)
ch <- 1 // panic

所以“要不要关”，从一开始就不是一个资源管理问题。

后来我慢慢意识到一个更重要的事实：关闭 channel，本质上是一种广播行为。

当一个 channel 被关闭时：

接收方仍然可以继续读
读到的将是零值，并且可以通过第二个返回值判断结束
所有正在阻塞等待接收的 goroutine，都会被同时唤醒

v, ok := <-ch
if !ok {
    // channel 已关闭，且不会再有新数据
}

这意味着，close 表达的并不是“我不想用了”，而是：我明确告诉所有接收方：不会再有新数据了。

从这个角度再回来看“谁负责关闭 channel”，答案就变得清晰了：谁负责发送最后一个值，谁负责关闭 channel。

更具体一点：

只有发送方才应该关闭 channel
接收方永远不应该关闭它
多发送方场景下，通常不由具体某一个 goroutine 来关

原因其实很朴素：

接收方并不知道“还有没有人会继续发送”，它没有这个全局视角。

如果接收方擅自关闭，就等于替别人做了生命周期决策。

// 常见且安全的模式
go func() {
    defer close(ch)
    for _, v := range data {
        ch <- v
    }
}()

这里的 close，不是清理，而是一个明确的完成信号。

在多发送者的场景下，这个问题会变得更直观。

如果多个 goroutine 同时往同一个 channel 发数据：

go worker1(ch)
go worker2(ch)

这时几乎可以肯定：任何一个 worker 都不适合去关闭这个 channel。

通常的做法反而是：

由一个“协调者”持有关闭权
或者通过 sync.WaitGroup 等方式，等所有发送者结束后统一关闭

go func() {
    wg.Wait()
    close(ch)
}()

这里关闭 channel 的 goroutine，本质上是站在“发送方整体”的立场。

从写代码的体验上看，我后来会把 close(channel) 当成一句语义非常重的话：它不是一个“善后动作”，而是并发协议的一部分。

什么时候关闭、由谁关闭、关闭意味着什么，这些问题如果想不清楚，代码往往就会开始变得脆弱。

所以这个问题最终并不是“谁来写 close”，而是：你有没有想清楚，这条 channel 在你的并发结构里，什么时候才算真正结束。

41. 使用 channel 避免共享状态

当前问题存在示例代码，可以前往GitHub查看

在我刚接触 Go 并发时，“使用 channel 避免共享状态”这句话其实有点抽象。

因为在 PHP 的经验里，共享状态几乎是默认存在的：数据库、缓存、全局变量、单例服务……它们并不是被避免的对象，而是被管理、被约定、被约束的对象。

所以一开始，我很自然地会把并发问题理解成：既然状态是共享的，那我该如何保证它是安全的。

var mu sync.Mutex
var wg sync.WaitGroup
count := 0

wg.Add(2)

go func() {
	defer wg.Done()

	mu.Lock()
	count++
	mu.Unlock()
}()

go func() {
	defer wg.Done()

	mu.Lock()
	count++
	mu.Unlock()
}()

wg.Wait()
fmt.Println(count)

这种写法并没有错，但它隐含了一个前提：所有 goroutine 都必须知道这份状态的存在，并且遵守同一套访问规则。

一旦有一个地方破坏了规则，问题就会变得很难追踪。

而当我开始用 channel 重写类似逻辑时，思路发生了一个比较明显的变化。

关注点不再是“怎么保护这份数据”，而是变成了：这份状态到底应该归谁所有。

比如下面这个例子里，我让多个 goroutine 只负责“产生数据”，

而把“累加结果”这件事，交给一个专门的接收者来完成：

ch := make(chan int)
var wg sync.WaitGroup

// 启动多个发送者
for i := 1; i < 10; i++ {
	wg.Add(1)
	go func(val int) {
		defer wg.Done()
		ch <- val
	}(i)
}

// 启动接收者，独占状态
resultChan := make(chan int)
go func() {
	total := 0
	for v := range ch {
		total += v
	}
	resultChan <- total
	close(resultChan)
}()

// 等待所有发送完成后再关闭 channel
go func() {
	wg.Wait()
	close(ch)
}()

result := <-resultChan
fmt.Println("总和:", result) // 输出: 总和: 45

在这段代码里，真正“持有状态”的，只有接收者那个 goroutine。

total 从头到尾只存在于它自己的执行上下文中，其他 goroutine 既不知道它的存在，也没有任何方式去修改它。

这时候，“避免共享状态”这句话才开始变得具体起来。

不是说状态消失了，而是：状态被明确地收敛到了一个地方。

另外一个让我印象很深的点，是 channel 在这里自然地承担了“边界”的角色。

发送者只负责一件事：我把值送出去，至于你怎么用，我不关心。

接收者只负责另一件事：我顺序地接收这些值，并维护我自己的状态。

至于 channel 什么时候结束，也不是由接收者来猜的，而是由发送方整体明确地给出信号：

wg.Wait()
close(ch)

这一行代码，本质上是在说：不会再有新的数据了，你可以放心收尾了。

从这个角度回头看，channel 并不是在“帮我解决共享状态的问题”，而是在改变我设计并发代码的默认路径。

与其先假设状态是共享的，再想办法把它保护起来，不如一开始就问清楚：这份状态到底有没有必要被共享。

而 channel，恰好给了我一种把这个问题落到代码结构里的方式。

42. channel 常见死锁场景分析

当前问题存在示例代码，可以前往GitHub查看

channel 的死锁并不是偶发事故，而是非常稳定地出现在几种固定结构里。

而且这些死锁，往往不是因为代码写错了，而是因为并发关系没有被完整表达出来。

最常见的一类，是没有接收者的发送。

ch := make(chan int)
ch <- 1

这段代码本身没有任何语法错误，但如果它运行在当前 goroutine 里，就会直接卡住。

原因也很直白：无缓冲 channel 的发送，必须等到有人接收才能完成。

这种死锁的本质，不是“忘了开 goroutine”，而是：你写下了一次通信，却没有给它安排对应的另一端。

另一类很容易出现的，是接收者在等一个永远不会结束的 channel。

ch := make(chan int)

go func() {
    ch <- 1
}()

for v := range ch {
    fmt.Println(v)
}

这里的 range ch 看起来很自然，但它隐含了一个前提：这个 channel 迟早会被关闭。

如果没有任何地方 close(ch)，接收者就会一直等下去。

这个问题在代码量变大之后尤其隐蔽，因为你很难第一眼看出“到底谁该负责关闭”。

第三类，是缓冲 channel 被写满，却没有人再继续接收。

ch := make(chan int, 2)

ch <- 1
ch <- 2
ch <- 3 // 阻塞

这里不是因为 channel 有缓冲就“更安全”，而是：缓冲只是延后了同步发生的时间，并没有消除同步本身。

当缓冲区写满之后，发送方仍然必须等待接收方出现。

如果接收方的生命周期已经结束，或者根本不存在，死锁依然会发生。

还有一类，在结构上更“高级”，也更常出现在真实代码里：goroutine 之间互相等待，但没有任何一方能够先继续往下走。

ch1 := make(chan int)
ch2 := make(chan int)

go func() {
    ch1 <- 1
    <-ch2
}()

go func() {
    ch2 <- 1
    <-ch1
}()

这里的死锁，并不是因为 channel 用错了，而是因为：通信顺序本身是矛盾的。

每个 goroutine 都在等待对方先完成某一步，但这一步永远不会发生。

把这些场景放在一起看，我后来意识到一件事：channel 的死锁，几乎都不是“技术细节问题”，而是协议问题。

每一个 channel，都隐含了一套并发协议：

谁负责发送
谁负责接收
什么时候开始
什么时候结束

只要其中任何一条没有被明确表达出来，死锁就很容易出现。

所以我现在反而会把“遇到 channel 死锁”当成一个信号：不是去急着修这一行代码，而是回头检查，我是不是有一段通信关系没有被完整地想清楚。

从这个角度看，channel 的死锁并不是 Go 的坑，而是 Go 把并发设计中的问题，非常诚实地暴露了出来。

十、context：协程的生命周期管理

43. context 的设计初衷

当前问题存在示例代码，可以前往GitHub查看

在一开始看 context 的时候，我其实是有点困惑的。

在 PHP 的世界里，请求本身就像一个天然的「生命周期边界」：

请求进来，代码从上往下执行；请求结束，进程要么退出、要么回到空闲池子里等待下一个请求。

不需要显式告诉谁“该结束了” ，一切都会自然结束。

但在 Go 里，这个前提并不存在。

context 的设计初衷，并不是为了“传参数”，而是为了“传递一件事”：你应该什么时候停下来

Go 选择了 goroutine 这种极轻量的并发模型之后，就顺带引入了一个问题：goroutine 一旦启动，并不会因为“调用它的函数返回了”而自动结束。

换句话说，在 Go 里：

函数返回 ≠ 工作结束
请求结束 ≠ 所有相关逻辑结束

如果不额外做点什么，goroutine 是可以脱离请求、脱离调用栈，继续活着的。

从这个角度再看 context，它更像是一种跨调用栈的“取消信号”机制。

它解决的并不是“我怎么把数据往下传”，而是：

上游什么时候决定放弃这次操作
下游如何感知“这件事已经没有继续做下去的意义了”

而且这个“放弃”，往往并不是错误，只是时机到了。

在 PHP 里，这个判断通常是隐含的：

客户端断开了
请求超时了
框架决定结束响应

你几乎不用思考：如果这个请求已经结束了，那我刚刚启动的逻辑会怎样？

因为答案通常是：它已经不复存在了。

但在 Go 里，如果你在处理一个 Web 请求时：

启动了一个 goroutine 去查数据库
又启动了一个 goroutine 去调第三方接口
甚至再包了一层异步重试逻辑

那么当客户端断开连接的那一刻：谁来告诉这些 goroutine：你们可以停了？

context 正是为了解决这个“通知链条”问题而出现的。

我后来慢慢意识到，context 本质上并不是一个“控制工具”，而是一种协作约定。

它并不会强制终止 goroutine，也不会替你回收资源。

它只是提供了一种统一、可传播的方式，去表达一件非常简单的状态：这件事情，还值得继续做吗？

至于要不要停、怎么停，完全取决于 goroutine 自己是否愿意去尊重这个信号。

44. context.WithCancel / Timeout / Deadline

当前问题存在示例代码，可以前往GitHub查看

在理解了 context 是“用来传递是否还值得继续”这个信号之后，再回头看

WithCancel、WithTimeout、WithDeadline，我反而没那么纠结它们的 API 差异了。

它们本质上都在做同一件事：创建一个“有明确结束条件”的 context。

区别只在于：这个“结束”的决定，是由谁、在什么时候做出的。

context.WithCancel 给了我一种最“显式”的感觉。

它并不关心时间，也不关心外部世界发生了什么，
它只是告诉你一件事：

我现在创建了一个 context
但什么时候结束，由我来决定

这种模式在 Go 里非常常见，尤其是：

上游逻辑已经确定不再需要结果
或者某个条件已经满足，后续工作变得多余

在 PHP 的语境里，这种“我说停就停”的能力其实很少显式存在，因为请求结束本身就已经是一次“全局 cancel”。

// 创建一个可取消的上下文，ctx为上下文，cancel为取消函数
ctx, cancel := context.WithCancel(context.Background())

go func() {
	for {
		select {
		case <-ctx.Done():
			fmt.Println("收到取消信号，退出 goroutine")
			return
		default:
			fmt.Println("goroutine 正在工作")
			time.Sleep(500 * time.Millisecond)
		}
	}
}()

time.Sleep(2 * time.Second)
cancel() // 主动告诉它：不用再干了
time.Sleep(1 * time.Second)

context.WithTimeout 和 context.WithDeadline，则更像是把“放弃的决定”交给时间。

这点一开始我有点不太适应。

在 PHP 中，超时往往是：

nginx 超时
php-fpm 超时
数据库超时
或者框架层统一兜底

这些超时是外部环境强加的限制，你写代码时，往往只是被动接受。

但 Go 把这个选择权下放到了代码层面。

// 创建一个带超时自动取消的上下文，2秒后超时自动取消，ctx为上下文，cancel为取消函数可以提前手动调用
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

go func() {
	for {
		select {
		case <-ctx.Done():
			fmt.Println("超时了，不等了")
			return
		default:
			fmt.Println("还在尝试完成任务")
			time.Sleep(500 * time.Millisecond)
		}
	}
}()

time.Sleep(3 * time.Second)

// 创建一个在指定绝对时间点自动取消的上下文，ctx为上下文，cancel为取消函数可以提前手动调用
deadline := time.Now().Add(2 * time.Second)
ctx, cancel := context.WithDeadline(context.Background(), deadline)
defer cancel()

go func() {
	for {
		select {
		case <-ctx.Done():
			fmt.Println("超过截止时间，结束")
			return
		default:
			fmt.Println("在截止时间前尝试完成")
			time.Sleep(500 * time.Millisecond)
		}
	}
}()

time.Sleep(3 * time.Second)

WithTimeout 给的是一种相对时间的承诺：从现在开始，如果这件事在 N 时间内还没完成，那就算了。

而 WithDeadline 更像是在说：到某一个确定的时间点之前，如果还没结束，就不值得继续了。

这两者在效果上几乎一致，但表达的意图略有不同：

一个是“我最多愿意等这么久”
一个是“我只能等到这个时间点”

在复杂调用链里，这种区别有时并不是给机器看的，而是给未来的自己或协作者看的。

慢慢理解这些之后，我开始意识到一个以前没太注意的点：

这些 context 并不是为了“让 goroutine 更聪明”，而是为了让“放弃变得可传播”。

一旦上游决定放弃：

子 context 会被一并取消
下游所有愿意监听这个信号的 goroutine，都能同步感知

这是一种非常“反脚本语言”的思路。

在脚本语言里，代码天然是线性的、短命的，“放弃”通常意味着异常、return、或者进程结束。

而在 Go 里，“放弃”被拆解成了一种状态，它可以被检查、被传递、被尊重，也可以被忽略。

45. 为什么 context 不应该传业务参数

当前问题存在示例代码，可以前往GitHub查看

一开始看到「context 不应该传业务参数」这条约定时，我其实是有点不服气的。

因为站在一个长期写 PHP 的人的角度，这件事看起来既顺手又合理：反正函数参数要往下传，那多塞一个进去有什么问题？

而且 context 本来就是“贯穿整个调用链”的那个东西，不正好吗？

但后来我慢慢意识到，这个约定并不是语法洁癖，而是在刻意保护 context 的语义边界。

context 被设计出来，是为了解决一件非常单一的事情：这条执行链，现在还有效吗？

它关心的是生命周期，而不是业务含义。

一旦你开始往 context 里塞业务参数，这两件事就被强行绑在了一起。

最直观的问题是：context 会被“越传越远” 。

在 Go 的习惯用法里，context 往往会一路传到：

数据库访问层
RPC / HTTP 客户端
缓存、队列、第三方 SDK

这些地方之所以接收 context，并不是因为它们关心你的业务，而是因为它们愿意尊重“取消 / 超时”这个信号。

如果这时候 context 里还混着：

userId
orderId
一些业务配置

那么问题就来了：这些底层组件 理论上不应该知道，却 技术上完全可以拿到。

context 在这里就从一个“公共信号”，变成了一个隐形的全局变量。

第二个让我开始警惕的点是：业务参数一旦进了 context，就很难再被替换或约束。

在 PHP 里，如果我想改一个函数的参数结构，影响范围通常是清晰的、可见的。

但 context 是“无类型约束”的：

ctx = context.WithValue(ctx, "user", user)

这种写法短期看很省事，但从阅读代码的角度来说，它几乎是不可发现的依赖。

你在看一个函数签名时：

func DoSomething(ctx context.Context) error

你完全无法知道：

它是否依赖某个业务值
依赖的是哪个 key
在什么情况下这个值是必须存在的

依赖被藏起来了，而隐藏依赖，几乎永远都是坏消息。

还有一个点，是我后来才意识到的：context 的取消是“传染性”的，但业务数据不该是。

当你从一个 context 派生出子 context 时：

取消信号会自动向下传播
超时和 deadline 也会一起继承

但如果你把业务参数塞进去，它们也会被不加区分地继承。

这意味着：一个原本只属于“请求级别”的业务数据，可能会被带进一些生命周期更短、语义完全不同的子任务中。

这在逻辑上是很混乱的。

后来我开始把 context 当成一种非常克制的基础设施。

它只回答三个问题：

这件事还能不能继续？
有没有超时或截止时间？
如果不能继续了，为什么（ctx.Err()）

除此之外，它刻意什么都不管。

如果你把业务参数塞进去，其实是在把一个“生命周期问题”，悄悄升级成了一个“数据承载问题”。

所以我现在更愿意接受那条看起来有点教条的建议：context 只用来传控制信号，不用来传业务含义。

46. Web 请求结束后 goroutine 应该如何退出

当前问题存在示例代码，可以前往GitHub查看

在 PHP 中，一个 Web 请求的结束，本身就是一次强制的生命周期收束：

请求返回
脚本执行结束
变量被销毁
资源被回收

哪怕你在请求里写了看起来很“异步”的代码，本质上也只是同步执行的另一种表达方式：请求一停，世界就停了。

但在 Go 里，请求结束这件事，本身不会自动影响 goroutine。

我一开始的直觉是这样的：Web 请求结束了，那我刚刚启动的 goroutine 应该也就“没用了”吧？

但 Go 并不会替你做这个判断。

你在 handler 里 go func() { ... }() 启动的 goroutine：

不属于这个 handler
不属于这个请求
只属于 runtime

如果你什么都不做，它是可以在请求返回之后继续跑的。

所以问题的关键，并不是：goroutine 会不会退出？

而是：你有没有告诉它：请求已经结束了？

在标准的 Go Web 框架中（不论是 net/http 还是上层封装），

请求级别的 context 往往会在以下时机被取消：

客户端断开连接
请求处理完成
超时或被中间件终止

这意味着，请求结束本身并不会“杀死 goroutine” ，它只是会让 ctx.Done() 变成可读状态。

如果把这个过程写成最简的结构，大概是这样：

func handler(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()

	go func() {
		select {
		case <-ctx.Done():
			fmt.Println("请求结束了，我该退出了")
			return
		default:
			doSomething()
		}
	}()

	w.Write([]byte("response"))
}

这里真正决定 goroutine 是否退出的，不是请求是否结束，而是 goroutine 有没有在合适的位置检查 context。

如果它检查了，并选择尊重这个信号，它就能“正确退出”；

如果它没检查，那它就会继续跑，直到逻辑自然结束，或者永远不结束。

这也是我后来慢慢接受的一个事实：

在 Go 里，goroutine 的退出是“协作式”的，而不是“附带发生的”。

Web 请求结束，只是一个信号源；

goroutine 是否结束，是它自己的责任。

在实践中，这通常意味着两件事：

不要启动“脱离 context 的 goroutine”
所有可能长期运行的逻辑，都应该能被 ctx.Done() 打断

尤其是：

循环
阻塞 IO
重试逻辑
等待外部资源

如果这些地方没有 context 的参与，
那 Web 请求结束与否，对它们来说是完全无感的。

所以我现在看“Web 请求结束后 goroutine 应该如何退出”这个问题，答案反而变得很朴素：它不会“应该”自动退出，除非你从一开始，就让它知道什么时候该退出。

而这个“知道”的方式，几乎永远就是：context。

47. context 泄漏的隐患

当前问题存在示例代码，可以前往GitHub查看

这里的“泄漏”，并不是 context 本身没被释放，而是围绕着 context 建立的那整套协作关系，没有被正确结束。

context 最大的特点是：它本身几乎什么都不做，但很多东西都会围着它转。

一旦你用 WithCancel / WithTimeout / WithDeadline 创建了一个 context，你其实同时创建了几件事：

一个可以被关闭的 Done() channel
可能存在的定时器
一条向下传播的取消链路

如果这条链路的“源头”没有被正确收束，下游所有依赖它的 goroutine，就都有可能一直活着。

最常见、也最容易被忽略的一种情况，是忘记调用 cancel。

func doSomething() {
	ctx, _ := context.WithTimeout(context.Background(), time.Minute)

	go func() {
		<-ctx.Done()
		fmt.Println("结束")
	}()
}

从逻辑上看，这段代码“好像也没问题”：一分钟后，context 自然会 Done。

但问题在于：在这一分钟之内，这条 context 链路始终是“活的” 。

如果这是一个高频调用的函数，那你实际上是在不断地创建：

定时器
goroutine
等待被取消的上下文

而这些东西，本来是可以更早被回收的。

这也是为什么 Go 的习惯用法里，总会看到那句：

defer cancel()

它并不是为了“正常路径”，而是为了异常路径和提前返回。

另一种更隐蔽的泄漏，是goroutine 没有正确监听 context。

ctx, cancel := context.WithCancel(context.Background())

go func() {
	for {
		doSomething()
	}
}()

cancel()

这里即使你调用了 cancel()，context 也确实已经 Done 了，但这个 goroutine 根本不知道这件事。

从调用者的视角来看：我已经“取消”了

但从 goroutine 的视角来看：我什么都没收到

这时候泄漏的不是 context，而是本该结束的 goroutine。

还有一种我觉得更“工程化”的问题：context 的作用域被拉得过大。

如果你：

把一个请求级别的 context 存起来
传给生命周期明显更长的后台任务
或者挂到全局结构中复用

那这个 context 的取消时机，就已经和它所控制的 goroutine 不匹配了。

结果往往是：

该结束的没结束
不该结束的被过早结束
或者干脆谁也控制不了谁

这种情况下，你很难说是“谁泄漏了”，但系统行为一定会开始变得不可预测。

所以我现在理解的“context 泄漏”，并不是一个单点错误，而是一种协作失败的后果。

它通常表现为：

goroutine 数量悄悄增长
请求已经结束，但后台还在工作
程序没有明显报错，却越来越“不干净”

而根源往往很朴素：

cancel 没有被调用
Done 没有被监听
生命周期边界画错了地方

十一、并发安全：不是所有地方都要锁

48. data race 是怎么产生的

当前问题存在示例代码，可以前往GitHub查看

在我一开始理解并发安全的时候，很容易把「data race」和「并发」本身混在一起，仿佛只要用了 goroutine，就天然和 data race 挂钩。

但慢慢拆开来看，其实 data race 并不是「并发导致的问题」，而是并发访问共享数据时，缺乏明确约束才出现的结果。

更具体一点，一个 data race 出现，通常同时满足几个条件：

同一块内存，被多个 goroutine 同时访问
至少有一次访问是写操作
这些访问之间，没有任何同步手段来建立顺序关系

这几个条件里，「同时」并不是指物理意义上的绝对同时，而是 Go 运行时和 CPU 层面没有办法保证它们的执行顺序。

哪怕在你眼里代码是顺序写的，只要没有同步原语，调度器就有权在任何时刻打断、切换、重排。

这点和 PHP 的体验差异非常大。

在 PHP 里，大多数时候请求是单线程模型：

一个请求，一套内存
变量生命周期和请求绑定
几乎不会出现「两个执行单元同时改一个变量」

所以在 PHP 中，我很少需要显式去思考「某个变量正在被谁同时读写」。

而在 Go 里，只要把一个变量暴露给多个 goroutine，这个问题就立刻成立。

一个容易被忽略的点是：data race 和逻辑错误不是一回事。

比如下面这种情况，从业务逻辑上看，结果「大概率」是对的，但它依然是 data race：

多个 goroutine 同时对一个 int 自增
没有锁，也没有原子操作
最终结果可能看起来「差不多正确」

问题不在于结果是不是偶尔对，而在于：Go 语言规范层面，已经不再对程序行为做任何保证。

这也是为什么 Go 会有 race detector。

它不是在帮你找“会不会出 bug”，而是在告诉你：这里的内存访问顺序是不被定义的

换句话说，data race 本质上不是“线程安全没做好”，而是程序已经越过了语言和运行时愿意为你兜底的边界。

还有一个我后来才意识到的误区： “只读就没问题”并不总成立。

如果一个变量在「初始化阶段」被写，之后只读，那么这是安全的；

但如果是「某些 goroutine 在读，另一些 goroutine 偶尔在写」，哪怕写的频率很低，data race 依然成立。

Go 并不会因为你“几乎不写”就宽容你。

从这个角度看，data race 并不是一个实现层面的 bug，而更像是一种设计层面的警告：你现在对共享数据的所有权和访问时序，其实并没有想清楚。

而后面要不要加锁、用 RWMutex、用 channel，甚至干脆复制数据，本质上都是在回答同一个问题：

谁在什么时候，拥有什么数据的修改权。

等这个问题明确了，data race 往往也就自然消失了。

49. mutex 与 RWMutex 的使用边界

当前问题存在示例代码，可以前往GitHub查看

在理解了 data race 是「共享数据的访问顺序不再受语言保证」之后，mutex 的位置就变得清晰了一些：它并不是为了“让并发变安全”，而是人为地给并发访问加上一条明确的顺序。

sync.Mutex 是最直接的一种方式。

它的语义非常朴素：同一时间，只有一个 goroutine 能进入临界区。

不管你是读还是写，只要进来了，别人就得等。

这也是我一开始最容易接受的点：当我还没完全想清楚并发模型的时候，用 mutex，至少能保证「不会同时改」。

但慢慢就会发现，mutex 的问题不在“能不能用”，而在于它什么都管：

读要等写
读要等读
哪怕只是看一眼状态，也要排队

这时候 RWMutex 看起来就很诱人了。

它把访问拆成两类：

读锁（RLock） ：多个 goroutine 可以同时持有
写锁（Lock） ：独占，且会阻塞所有读

从模型上看，它表达了一种更精细的意图：这个共享数据，大多数时候只是被读取，只有少数时候会被修改。

但真正用起来，我反而变得更谨慎了。

原因并不是 RWMutex 有什么“坑”，而是它对使用场景的要求非常严格。

如果写操作并不罕见，或者读写比例本身并不稳定，那么 RWMutex 的优势会迅速消失，甚至可能比普通 Mutex 更差

因为你付出了更复杂的锁管理成本，却没有换来足够的并发收益。

更重要的是，RWMutex 在语义上其实放大了一个设计前提：你必须非常确定，哪些代码路径是“纯读”，哪些是“可能写” 。

一旦这个判断出错，比如：

你以为是读，但内部偷偷改了状态
读操作依赖某个「可能被写」的复合结构
写操作被拆散在多个函数里，不容易整体加锁

那么 RWMutex 带来的不是性能提升，而是理解成本和出错概率的上升。

所以在我的理解里：

Mutex 更像是“保守但稳妥”的选择

它牺牲了一部分并发性，但换来了更简单、直接的心智模型。
RWMutex 更像是一种“性能假设成立时的优化手段”

而不是默认选项。

还有一个让我重新看待 RWMutex 的点是：它并不会帮你解决“谁拥有数据”的问题，只是把锁分成了两种。

如果你已经搞不清楚：

这个数据到底被谁负责修改
写发生在什么生命周期阶段
是否真的存在“长期只读”的稳定状态

那么引入 RWMutex，往往只是把模糊的边界变得更复杂。

反过来看，当我能清楚地说出：

初始化阶段：写
运行阶段：只读
偶发配置更新：集中写

这种情况下，RWMutex 才更像是在把已有的设计事实编码进同步原语里，而不是靠它来“补救并发安全”。

所以对我来说，mutex 和 RWMutex 的使用边界，并不是性能数字，而是一个更偏设计的问题：我是否真的理解了这份数据在并发环境下的生命周期和访问模式。

如果答案还是否定的，那越简单的锁，反而越诚实。

50. sync.Once 的实际应用场景

当前问题存在示例代码，可以前往GitHub查看

在第一次看到 sync.Once 的时候，我其实有点疑惑：这个东西看起来很“窄”，好像只解决一个非常具体的问题：只执行一次。

但真正用过之后才发现，它解决的并不是“次数问题”，而是并发环境下的初始化边界问题。

很多并发问题，本质都集中在「第一次」：

第一次创建连接池
第一次加载配置
第一次初始化某个全局结构
第一次启动后台 goroutine

在单线程世界里，这些事情天然是顺序发生的；

但在 Go 里，只要有多个 goroutine 同时进来，“第一次”本身就变成了一个竞争点。

一个直觉做法是用 mutex 包起来：

判断是否初始化
如果没有，就初始化
然后释放锁

逻辑上没错，但这个方案里，其实你在手动维护一个状态机：“有没有初始化过”，以及“现在谁有权初始化”。

sync.Once 把这件事直接抽象成了一种语义：无论多少 goroutine 调用，传进去的函数，只会被执行一次。

而且更重要的是，这个“一次”是并发安全、并且带有内存可见性保证的。

也就是说，Once 内部不仅解决了“只跑一次”，还顺手帮你解决了「初始化完成后，其他 goroutine 能不能看到完整结果」这个问题。

我后来意识到，Once 适合的并不是“所有只能跑一次的逻辑”，而是初始化型逻辑，尤其是这几类：

全局或包级资源的延迟初始化
比如某个 client、缓存、配置对象，不希望在 init() 里就加载，但又必须保证只初始化一次。
成本高、但并不一定会用到的准备工作
与其启动时全做，不如等第一次真的需要的时候再做，但又不能并发重复做。
需要对外暴露一个“随时可用”的接口
调用方不需要关心你是否初始化过，只要用就行。

在这些场景下，Once 表达的不是“控制流程”，而是一种所有权声明：初始化这件事，不属于任何一个具体 goroutine，而由 Once 统一负责。

同时，它也隐含了一个非常重要的边界：Once 只负责“执行一次”，不负责“是否成功”。

如果初始化函数里出错了：

Once 仍然认为“已经执行过”
后续调用不会再重试
错误处理必须由你自己设计

这点让我在使用 Once 时变得格外谨慎。

它更适合那种「要么成功，要么直接 panic / fail fast」的初始化，而不太适合需要复杂重试策略的场景。

还有一个容易被忽略的点是：Once 并不是用来替代锁的。

它解决的是「第一次」，而不是「每一次」。

Once 之后的数据访问，如果仍然存在并发读写，锁依然是锁，channel 依然是 channel。

所以在我的理解里，sync.Once 的实际价值不在于“少写几行代码”，而在于它帮我把一个模糊的并发问题，收敛成了一句话就能说明白的设计事实：有些事情，在并发系统里，应该只发生一次，而且不属于任何人。

当这个事实成立的时候，Once 往往是最直接、也最不容易被误用的表达方式。

51. 用 channel 替代锁的设计思路

当前问题存在示例代码，可以前往GitHub查看

一开始接触 Go 的并发模型时，很容易把 channel 当成一种“更高级的锁”：不用显式加解锁，看起来更优雅，好像也更 Go。

但后来我慢慢意识到，这样理解反而会把 channel 用窄了。

channel 并不是在“保护共享数据”，而是在尝试让共享本身消失。

锁的出发点是：数据是共享的，我们需要约束谁什么时候能碰它。

而 channel 的出发点更像是：如果数据不共享了，那还需要锁吗？

这两种思路，看起来只是实现不同，本质上却是所有权模型的差异。

用 mutex 时，常见的结构是：

多个 goroutine
共同持有一份状态
通过锁来协调访问顺序

而用 channel 的时候，更倾向于变成：

某一份状态，只属于某一个 goroutine
其他 goroutine 只能通过发送消息，间接影响它
状态的修改，被串行化在这个 goroutine 内部

这里真正发生变化的不是“有没有并发”，而是：谁有权直接读写数据。

当我把 channel 用在这种模型里时，它更像是在表达一个事实：这份数据的生命周期和一致性，由一个 goroutine 负责。

而 channel，只是这个 goroutine 对外暴露的沟通接口。

这也是为什么，用 channel 替代锁，往往不是简单地“把 mutex 换成 channel”，而是需要连带着调整结构设计。

如果状态本身仍然被多个 goroutine 随意访问，那 channel 只会变成另一种形式的共享，而不是解法。

一个我后来比较认可的判断标准是：

如果你关注的是状态一致性，锁更直接
如果你关注的是状态所有权和流转，channel 更自然

比如在一些场景里：

任务队列
事件分发
后台状态机
聚合统计（计数、累积）

用 channel 的时候，你描述的是「事情发生了」，而不是「我现在要改一个变量」。

当然，这种设计也不是没有代价。

用 channel 往往意味着：

状态被集中在某个 goroutine
调试路径可能更“绕”
需要更清楚地设计消息结构和生命周期

如果只是为了避免加锁，而强行引入 channel，反而可能让系统更难理解。

所以对我来说，「用 channel 替代锁」并不是一个技巧，而是一种设计取向的选择：

我是希望继续接受“共享状态”的事实，只是把访问变安全
还是愿意为此调整结构，把共享变成消息，把并发变成顺序

当后者成立时，channel 才真的发挥了它的价值。

否则，它和 mutex 一样，都只是工具而已。

52. 复制数据 vs 加锁的取舍

当前问题存在示例代码，可以前往GitHub查看

在并发问题里，「复制数据 vs 加锁」经常被摆在一起对比，好像是在做一次性能或优雅度的选择。

但我后来慢慢意识到，这个取舍点其实并不完全在“技术层面”，而是在你愿不愿意为数据付出边界成本。

加锁的前提是一个默认事实：这份数据是共享的，而且会被持续共享下去。

复制数据则隐含了另一个判断：在某个时刻之后，这份数据不再需要被共同修改。

这两种假设一旦不同，后续的设计方向基本就已经定了。

用锁的时候，你关心的是：

锁粒度够不够小
读写比例是否合适
是否会形成竞争、阻塞、甚至死锁

而选择复制的时候，关注点会整体前移：

数据是不是足够小，或者可控
修改是否是阶段性的，而不是持续发生
下游是否真的需要“实时一致”的状态

我一开始会下意识地倾向于“少复制，多共享”，这大概是受了传统后端经验的影响：复制看起来像是在浪费内存，而锁看起来只是“多了一点同步” 。

但在 Go 的并发语境下，这种直觉经常是反过来的。

锁的成本并不只是运行时的开销，还有持续存在的心智负担，每一个访问点，都要记得：

我现在是不是在锁内
会不会和别的 goroutine 形成交叉
这个函数能不能被复用到别的上下文

而复制数据，往往是一次性的复杂度：

在边界处做一次 copy
后面的逻辑可以当作单线程来写
不再需要为并发关系兜底

这也是为什么在一些场景里，复制反而显得更“便宜”。

尤其是这几种情况：

请求级数据

每个请求一份，互不影响，本来就不该共享。
配置 / 快照类数据

更新不频繁，读很多，但读并不要求实时同步。
只读视图

下游只关心当前状态，不关心后续变化。

在这些地方，用复制明确切断并发关系，比精细地加锁要更直接。

当然，复制也不是没有边界。

当数据满足以下特征时，锁通常更合理：

体量很大，复制成本不可接受
更新频繁，几乎每次都要保持一致
数据天然就是一个“中心状态”，无法拆散

这时候，共享几乎是事实，锁只是对事实的承认。

所以我后来不太把「复制 vs 加锁」看成性能对比，而更像是在问一个设计问题：这份数据，真的需要被持续共享吗？

如果答案是否定的，那复制往往是一次性买断复杂度；

如果答案是肯定的，那锁的存在就是不可避免的长期成本。

十二、并发错误：必须亲手踩过的坑

53. goroutine 泄漏的几种常见写法

当前问题存在示例代码，可以前往GitHub查看

在我开始系统性地意识到 goroutine 泄漏这件事之前，其实很长一段时间里，我只是隐约感觉到：有些 goroutine 好像“没人管了” 。

它们不报错，也不影响主流程，但它们确实还活着。

下面这些写法，都是我后来回头看时，能明确意识到“这里已经具备泄漏条件”的例子。

最基础的一种，是等待一个永远不会再发生的接收。

package main

import (
    "fmt"
    "time"
)

func worker(ch chan int) {
    for {
        v := <-ch
        fmt.Println("received:", v)
    }
}

func main() {
    ch := make(chan int)

    go worker(ch)

    // 主 goroutine 什么都不做，只是等待一会儿退出
    time.Sleep(2 * time.Second)
    fmt.Println("main exit")
}

这段程序可以正常结束，go run 也不会报任何错误。

但在 main 退出之前，worker 已经卡在 <-ch 上了。

这里的关键不在于有没有循环，而在于：这个 goroutine 的退出条件完全依赖于一个外部假设：有人会往 ch 写数据或者关闭它。

一旦这个假设不成立，它就失去了返回的可能。

稍微“进阶”一点的写法，是使用 range ch 的消费者。

package main

import (
    "fmt"
    "time"
)

func consumer(ch <-chan int) {
    for v := range ch {
        fmt.Println("consume:", v)
    }
    fmt.Println("consumer exit")
}

func main() {
    ch := make(chan int)

    go consumer(ch)

    ch <- 1
    ch <- 2

    // 没有 close(ch)
    time.Sleep(2 * time.Second)
    fmt.Println("main exit")
}

从语义上看，这已经比直接 <-ch 安全得多，因为 range 是“为关闭而生”的。

但问题依然存在：如果没有人负责关闭这个 channel，这个 goroutine 就永远不会走到循环外。

你甚至已经写好了退出逻辑（consumer exit），只是它永远不会被触发。

另一类我后来觉得非常“隐蔽”的，是带 default 的 select。

package main

import (
    "fmt"
    "time"
)

func loop(ch <-chan int) {
    for {
        select {
        case v := <-ch:
            fmt.Println("received:", v)
        default:
            // 看起来很安全：不阻塞
        }
    }
}

func main() {
    ch := make(chan int)

    go loop(ch)

    time.Sleep(2 * time.Second)
    fmt.Println("main exit")
}

这段代码里，没有任何地方会“卡住”。

相反，它会一直运行。

问题在于：

这个 goroutine 没有任何退出条件，它只是在不断地证明自己还活着。

如果你在 default 里加点日志，很快就会意识到这不是“安全”，而是失控的常驻循环。

还有一类问题，其实和 channel、select 都没关系，而是“把 goroutine 当成一次性异步函数”。

package main

import (
    "fmt"
    "time"
)

func asyncTask() {
    for {
        fmt.Println("working...")
        time.Sleep(500 * time.Millisecond)
    }
}

func main() {
    go asyncTask()

    time.Sleep(2 * time.Second)
    fmt.Println("main exit")
}

在阅读这段代码的时候，很容易下意识地理解为：我异步执行了一个任务，主流程结束就结束了。

但真实情况是：asyncTask 本身是一个永远不会返回的函数。

一旦你在一个长期运行的服务中这样写，你就已经创建了一个永久 goroutine，只是没有给它任何边界。

到这里，我对 goroutine 泄漏的判断已经不太依赖“有没有 bug”，而更多依赖一个问题：如果我现在关掉调用方，这个 goroutine 会不会在设计上自然结束？

如果答案需要附带很多前提条件，那它大概率已经站在泄漏的边缘了。

54. channel 永远阻塞的原因

当前问题存在示例代码，可以前往GitHub查看

在我真正理解 channel 为什么会“永远阻塞”之前，其实有一个挺大的心理落差：channel 在语义上看起来是“通信工具”，但在行为上，它更像是一种非常严格的同步协议。

阻塞并不是异常，而是它的默认行为。

真正需要解释的反而是：为什么我们会在某些场景下，以为它不该阻塞。

最直接的一种情况，是最基础的发送 / 接收不对等。

package main

import (
    "fmt"
)

func main() {
    ch := make(chan int)

    ch <- 1

    fmt.Println("unreachable")
}

这段代码在逻辑上非常“直白”：我创建一个 channel，然后往里面塞一个值。

但它会直接卡死在 ch <- 1 这一行。

原因并不复杂：无缓冲 channel 的发送，必须等到有人接收才能完成。

如果站在 channel 的视角，这并不是“没人理我”，而是：我在等一个明确的交接时刻，但你从未安排过对方。

这里的阻塞不是偶发的，而是必然的。

稍微变一下形式，把接收放到 goroutine 里，阻塞的感觉就没那么直观了。

package main

import (
    "fmt"
)

func main() {
    ch := make(chan int)

    go func() {
        v := <-ch
        fmt.Println("received:", v)
    }()

    // 主 goroutine 提前结束
}

这段代码不会 panic，也不会报错，但什么都不会输出。

问题不在 channel，而在调度顺序和生命周期上：主 goroutine 很快就结束了，整个进程随之退出，接收方根本没有机会运行。

如果你在某个服务型程序里写了类似结构，就会得到另一种结果：接收 goroutine 活着，但发送永远没发生，或者反过来。

从外部看，它们都只是“在等”。

另一种我一开始没太当回事，但后来发现非常容易写出来的情况，是 range channel。

package main

import (
    "fmt"
)

func main() {
    ch := make(chan int)

    go func() {
        for v := range ch {
            fmt.Println(v)
        }
        fmt.Println("exit")
    }()

    ch <- 1
    ch <- 2

    // 没有 close(ch)
    select {}
}

这段代码的阻塞点并不在发送，而在接收。

range ch 的语义非常清晰：一直读，直到 channel 被关闭。

问题在于，如果你只是“停止发送”，但没有关闭 channel，那么在 channel 看来，世界并没有结束，它只是暂时没数据。

于是接收方就会一直阻塞在等待下一次发送上。

这里很容易出现一种错觉：“我已经不往里写了，为什么还不结束？”

因为对 channel 来说，“不再写”和“生命周期结束”是两件完全不同的事。

再往下看，就会遇到一些更“像业务代码”的阻塞。

package main

import (
    "fmt"
)

func main() {
    ch := make(chan int)

    select {
    case ch <- 1:
        fmt.Println("sent")
    }
}

这段代码里甚至没有接收方，但 select 的存在会让人误以为：“它至少不会一直卡着吧？”

但 select 并不会创造奇迹。

如果所有 case 都无法继续，它的行为和普通阻塞是完全一致的。

这里没有 default，所以 select 的含义其实是：我愿意在这里等，直到某个 case 可以执行。

而在这个程序里，这一天永远不会到来。

还有一种阻塞，是在你“觉得自己已经考虑周全”的情况下发生的。

package main

import (
    "fmt"
)

func main() {
    ch := make(chan int, 1)

    ch <- 1
    ch <- 2

    fmt.Println("done")
}

很多人第一次用有缓冲 channel 时，会把它理解成：“有点像队列，多塞几个应该没问题。”

但缓冲只是在容量范围内改变阻塞时机，并没有取消阻塞这个概念。

当缓冲满了，发送依然是同步的。

这段代码卡死在第二次发送上，其实是在提醒一件事：channel 不是消息系统，它只是一个带容量的同步点。

慢慢把这些情况放在一起看，我对“channel 永远阻塞”的理解反而变简单了。

它从来不是“偶然卡住”，而几乎总是因为下面这类原因之一：

发送和接收在数量或时序上不对等
接收方在等一个永远不会被 close 的 channel
select 里没有任何可能继续的 case
缓冲被当成了“无限容量”的错觉
goroutine 的生命周期比 channel 短或长，但设计时没对齐

channel 本身并不会判断你“是不是该结束了”。

它只会严格执行你写下的同步协议。

当你感觉它“永远阻塞”的时候，往往不是 channel 出了问题，而是：你其实已经写出了一个“永远等下去也合理”的程序。

55. for + goroutine 的经典陷阱

当前问题存在示例代码，可以前往GitHub查看

现在再看 for + goroutine，我已经很少把注意力放在“循环变量对不对”这种层面了。语言已经把这件事处理得足够符合直觉，反而是另外一些问题，被这个组合悄悄放大了。

第一个让我警觉的点，是启动了，但没人等。

package main

import (
    "fmt"
)

func main() {
    for i := 0; i < 5; i++ {
        go func(i int) {
            fmt.Println(i)
        }(i)
    }

    fmt.Println("main exit")
}

这段代码在语义上完全正确：值是对的，goroutine 也确实被启动了。

但从结构上看，它其实表达的是一件很模糊的事：

这些 goroutine 是否“重要”，以及它们是否需要完成，没有被代码回答。

for + goroutine 非常容易让并发变成一种“顺手就写了”的行为，而不是一个被明确建模的流程。

一旦你没有显式等待，它们就和调用方脱钩了。

在示例里，程序很快结束；

在服务里，它们可能会在请求结束后继续运行，变成你并未计划的后台任务。

第二个问题，是共享外部状态被并发放大。

package main

import (
    "fmt"
    "sync"
)

func main() {
    var result []int
    var wg sync.WaitGroup

    for i := 0; i < 5; i++ {
        wg.Add(1)
        go func(i int) {
            defer wg.Done()
            result = append(result, i)
        }(i)
    }

    wg.Wait()
    fmt.Println(result)
}

这里并没有任何“经典写法错误”：

循环变量是安全的
goroutine 也被正确等待了

但问题仍然存在，因为 result 是共享的。

for 循环的作用，在这里其实只是把一个本来就不安全的操作，瞬间并发执行了很多次。

这类问题特别容易被忽视，因为你会下意识觉得：我已经用 WaitGroup 了，结构是对的。

但 WaitGroup 只解决了“什么时候结束”，并不解决“是否可以并发写”。

第三个坑，往往出现在资源生命周期和 goroutine 生命周期错位的时候。

package main

import (
    "fmt"
    "os"
)

func main() {
    file, _ := os.Open("test.txt")
    defer file.Close()

    for i := 0; i < 3; i++ {
        go func(i int) {
            buf := make([]byte, 10)
            file.Read(buf)
            fmt.Println(i, string(buf))
        }(i)
    }
}

这段代码里：

file 的生命周期绑定在 main 上
goroutine 的执行时机是不确定的

for 循环结束得非常快，而 defer file.Close() 会在 main 返回时立刻执行。

于是就出现了一种结构性问题：资源已经被回收了，但使用它的 goroutine 还没开始，或者还没用完。

这里没有语法错误，也没有明显的并发冲突，但程序行为已经变得不可预测了。

再往后一个层次，是并发规模被无意中放大。

for _, task := range tasks {
    go handle(task)
}

这行代码在今天的 Go 里，语义非常干净，也非常诱人。

但它隐含了一个强假设：tasks 的规模是可控的，而且每个任务都适合同时执行。

一旦：

tasks 来自外部输入
数量不可预期
handle 内部阻塞或耗时

这个 for 循环，本质上就是在瞬间制造大量 goroutine。

这里的问题不是“并发本身”，而是：for + goroutine 让“并发数量”这件事变得太不显眼了。

所以现在我再看 for + goroutine，心里的判断标准已经很稳定了：

循环变量是不是安全，已经不是重点；

真正需要被回答的，是并发结构本身。

比如：

这些 goroutine 谁来等？
它们是否在访问共享状态？
它们依赖的资源是否还活着？
并发的规模是否被明确限制？

56. 并发 map 写导致的 panic

当前问题存在示例代码，可以前往GitHub查看

在我第一次遇到 并发 map 写 panic 的时候，其实并没有太多“并发出错”的直觉。

因为从代码结构上看，它往往并不复杂，甚至还挺直观。

直到我意识到：这不是一个“写法问题”，而是 Go 在这里做了一个非常强硬、非常明确的选择。

先从一个最小、也最容易复现的例子开始。

package main

import (
    "sync"
)

func main() {
    m := make(map[int]int)
    var wg sync.WaitGroup

    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func(i int) {
            defer wg.Done()
            m[i] = i
        }(i)
    }

    wg.Wait()
}

这段代码并不“偶发”出错，它几乎一定会 panic：

fatal error: concurrent map writes

这里没有 data race 的模糊空间，Go 运行时直接中断了程序。

这件事一开始让我挺不适应的，因为在很多语言里，这类问题的表现通常是：

数据错了
偶尔崩
或者什么都没发生，但结果不可信

而 Go 在这里的态度非常明确：一旦发现 map 被并发写，程序立刻终止。

关键在于：Go 的 map，从来就不是并发安全的数据结构。

它内部会在写入时：

扩容
重排 bucket
移动元素

这些操作本身就假设“当前只有一个写者”。

于是，一旦两个 goroutine 同时写 map，运行时与其让你得到一个“看起来还能用但已经损坏”的 map，不如直接告诉你：程序不成立。

这并不是一个“性能取舍”，而是一种设计态度。

更容易让人误判的，是下面这种“读写混合”的场景。

package main

import (
    "sync"
)

func main() {
    m := make(map[int]int)
    var wg sync.WaitGroup

    for i := 0; i < 5; i++ {
        wg.Add(1)
        go func(i int) {
            defer wg.Done()
            _ = m[i]
        }(i)
    }

    for i := 5; i < 10; i++ {
        wg.Add(1)
        go func(i int) {
            defer wg.Done()
            m[i] = i
        }(i)
    }

    wg.Wait()
}

很多人第一次看到 concurrent map writes，会误以为：是不是只有写写才不行，读写应该没事吧？

但在 Go 里，只要存在并发写，不论是否混着读，行为就是未定义的，运行时也可能直接 panic。

读本身是安全的，但读和写并发出现时，map 的内部状态已经不再可控。

我后来意识到一个很重要的点：这个 panic 并不是在提醒你“少用并发”，而是在逼你做结构选择。

一旦你决定让 map 出现在多个 goroutine 中，你就必须回答下面这些问题之一：

是不是应该用锁？
是不是应该把 map 的写集中到一个 goroutine？
是不是应该换一种数据结构？

Go 不会帮你在运行时“偷偷兜底”，而是要求你在设计时明确站队。

比如最直接的方式，是显式加锁。

package main

import (
    "fmt"
    "sync"
)

func main() {
    m := make(map[int]int)
    var mu sync.Mutex
    var wg sync.WaitGroup

    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func(i int) {
            defer wg.Done()
            mu.Lock()
            m[i] = i
            mu.Unlock()
        }(i)
    }

    wg.Wait()
    fmt.Println(m)
}

这段代码本身并不“高级”，但它非常清楚地表达了一件事：这个 map 是共享的，而且我承认这件事。

另一种思路，是干脆不共享。

package main

import (
    "fmt"
)

func main() {
    ch := make(chan int)
    m := make(map[int]int)

    go func() {
        for v := range ch {
            m[v] = v
        }
    }()

    for i := 0; i < 10; i++ {
        ch <- i
    }

    close(ch)
    fmt.Println(m)
}

这里 map 只存在于一个 goroutine 里，并发发生在 channel 上，而不是数据结构本身。

这类写法，本质上是在用结构规避问题，而不是“修补错误”。

所以现在我再看到 并发 map 写导致的 panic，已经不太会把它理解成“坑”了。

它更像是一道非常明确的边界线：只要你想让 map 被并发写，你就必须为这个决定负责。

panic 的存在，并不是 Go 太严格，而是它拒绝在数据结构已经不成立的情况下，继续假装程序还“能跑”。

而这也正是 Go 并发模型里一个非常一致的态度：问题要么在设计阶段被处理掉，要么在运行时被明确拒绝。

57. 如何通过结构设计避免并发 bug

当前问题存在示例代码，可以前往GitHub查看

在把前面那些并发问题逐个拆开之后，我慢慢意识到一件事：大多数并发 bug，其实不是“哪里没加锁”，而是“结构一开始就没想清楚”。

当我开始从“结构”而不是“修补”去看问题时，很多之前看起来零散的坑，反而能归到同一类原因里。

我现在判断一个并发设计是否危险，通常先看一个问题：并发发生在哪里？

如果并发发生在数据结构内部，那你接下来几乎一定会面对：

锁
竞态
生命周期错位
难以复现的问题

所以第一个结构层面的选择，是尽量把并发推到边缘，而不是让它渗透进核心数据。

type Store struct {
    m map[string]int
}

func (s *Store) Set(k string, v int) {
    s.m[k] = v
}

func (s *Store) Get(k string) int {
    return s.m[k]
}

如果这个 Store 被多个 goroutine 直接调用，那并发已经侵入了最核心的状态。

但如果换一个结构视角：

type request struct {
    key   string
    value int
}

func storeLoop(reqCh <-chan request) {
    m := make(map[string]int)
    for req := range reqCh {
        m[req.key] = req.value
    }
}

并发不再发生在 map 上，而是发生在 channel 的发送上。

map 本身重新变成了“单线程世界”的东西。

第二个我越来越在意的，是明确 goroutine 的所有权。

很多并发 bug，本质上都是因为某个 goroutine：

由谁创建，不清楚
由谁负责结束，也不清楚

一旦所有权模糊，生命周期就很容易失控。

go worker()

这行代码本身什么都没说清楚：

worker 是否重要？
是否必须完成？
什么时候结束？

如果换一种结构表达：

func startWorker(ctx context.Context) <-chan struct{} {
    done := make(chan struct{})
    go func() {
        defer close(done)
        for {
            select {
            case <-ctx.Done():
                return
            default:
                // do work
            }
        }
    }()
    return done
}

这里就非常明确了：

谁创建 worker
如何通知它退出
如何知道它已经结束

不是因为多写了几行代码更“规范”，而是结构上不再有模糊空间。

第三个结构层面的选择，是让“等待”变成显式行为。

for + goroutine 特别容易制造一种假象：事情已经开始了，就当它们会自己结束吧。

但在稳定的并发结构里，等待几乎总是被明确表达出来的。

var wg sync.WaitGroup

for _, task := range tasks {
    wg.Add(1)
    go func(task Task) {
        defer wg.Done()
        handle(task)
    }(task)
}

wg.Wait()

这段代码的意义，不只是“等所有 goroutine 结束”，而是在结构上宣告了一件事：这些任务是这个函数职责的一部分。

一旦你不等，它们就已经不属于当前结构了。

第四个我后来非常看重的点，是限制并发规模。

for _, task := range tasks {
    go handle(task)
}

这段代码的问题不在并发，而在无上限。

结构上更稳定的方式，往往会显式引入“容量”的概念。

sem := make(chan struct{}, 5)

for _, task := range tasks {
    sem <- struct{}{}
    go func(task Task) {
        defer func() { <-sem }()
        handle(task)
    }(task)
}

这里并发是否发生，是被结构明确控制的，而不是被 for 循环顺手放大的。

最后一个让我对并发 bug 看法发生变化的点，是：不要让并发和资源生命周期隐式耦合。

func process(file *os.File) {
    go func() {
        file.Read(...)
    }()
}

这段代码的问题，不是读文件，而是：file 的生命周期并不由 goroutine 控制。

结构更清晰的方式，往往会把资源和 goroutine 放在同一个边界内。

func process() {
    file, _ := os.Open("a.txt")
    defer file.Close()

    read(file)
}

或者反过来，把 goroutine 的生命周期交给外部。

所以现在再回头看并发 bug，我已经很少从“这里该不该加锁”开始思考了。

我更常问的是：

并发是不是发生在我希望它发生的地方？
数据是不是有且只有一个拥有者？
goroutine 的生命周期是否被明确建模？
等待、退出、容量，这些事情有没有被结构表达出来？

当这些问题在结构上已经被回答时，很多并发 bug，其实还没来得及出现，就已经被排除掉了。

十三、Go Web 中的生命周期意识

58. HTTP 请求在 Go 中的完整生命周期

当前问题存在示例代码，可以前往GitHub查看

在 Go Web 里，一个 HTTP 请求的生命周期是非常直观的。

服务启动后，net/http 开始监听端口，每一个进入的连接都会被交给独立的 goroutine 处理，请求从一开始就处在并发环境中。

一个最小的 HTTP 服务大概是这个样子：

package main

import (
	"fmt"
	"net/http"
)

func main() {
	http.HandleFunc("/hello", helloHandler)
	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func helloHandler(w http.ResponseWriter, r *http.Request) {
	fmt.Println("handler start")
	w.Write([]byte("hello"))
	fmt.Println("handler end")
}

启动这个程序，然后请求 /hello，你能清楚地看到：

handler start 打印时，请求刚刚进入你的代码；

handler end 打印完，这次请求在你这边的生命周期就结束了。

这里有一个很重要但容易被忽略的事实：helloHandler 这一次函数调用，本身就是请求生命周期在你代码里的全部体现。

Go 没有隐藏阶段，也没有额外的“请求对象生命周期管理”，你写的函数，就是边界。

当请求进入 handler 时，net/http 已经为你准备好了一个 *http.Request，而这个 request 上，绑定着一个非常关键的东西：Context。

我们把上面的例子稍微扩展一下，让 context 参与进来：

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"
)

func main() {
	http.HandleFunc("/work", workHandler)
	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func workHandler(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()

	result := doWork(ctx)

	w.Write([]byte(result))
}

func doWork(ctx context.Context) string {
	select {
	case <-time.After(3 * time.Second):
		return "work done"
	case <-ctx.Done():
		return "request canceled"
	}
}

现在访问 /work，如果你在 3 秒内主动断开连接（比如浏览器刷新或关闭），doWork 会立刻走到 ctx.Done() 分支。

这件事非常“Go”：请求并不是“一定会跑完”的，你的代码必须承认这一点。

在 PHP 的同步执行模型里，请求结束通常意味着脚本自然跑完；而在 Go 里，请求可以先结束，但 goroutine 仍然活着，只是 context 明确告诉你：这件事已经不值得继续做了。

当 workHandler 返回时，对 Go 来说，这次请求就已经结束了。响应被写出，连接可能被复用，而 *http.Request、ResponseWriter 都不再属于你。

这时如果我们引入一个常见但危险的写法，生命周期的问题就会立刻暴露出来：

package main

import (
	"fmt"
	"net/http"
	"time"
)

func main() {
	http.HandleFunc("/async", asyncHandler)
	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func asyncHandler(w http.ResponseWriter, r *http.Request) {
	go func() {
		time.Sleep(2 * time.Second)
		fmt.Println("async work done")
	}()

	w.Write([]byte("response sent"))
}

这个程序当然是能跑的，但它在语义上已经开始模糊请求的生命周期了：handler 已经返回，响应已经发出，但 goroutine 仍然在后台执行，而且它和这次 HTTP 请求已经没有任何正式的关系。

如果这个 goroutine 里还在使用 r、w、或者假设“这是一次合法的请求上下文”，那问题就不再是写法不优雅，而是生命周期已经被破坏了。

回过头来看，Go 中 HTTP 请求的完整生命周期其实非常短：

handler 被调用，请求进入你的代码
handler 返回，请求在你这里结束

中间所有你认为“顺理成章”的事情——数据库连接、goroutine、缓存、异步任务——都必须主动地对齐这个时间窗口。

所以这一节对我来说，更像是在建立一个认知前提：在 Go Web 里，请求不是一个模糊的过程，而是一段你必须明确尊重的生命周期。

59. handler、middleware、service 的职责边界

当前问题存在示例代码，可以前往GitHub查看

这一节在我看来，其实不是在讲“该怎么分层”，而是在回答一个更底层的问题：在 Go Web 里，谁对 HTTP 请求的生命周期负责到哪一步为止。

如果把请求当成一条时间线，那 handler、middleware、service 并不是三个并列的技术名词，而是对这条时间线不同区段的认领方式。

先从 handler 说起。

在 Go 里，handler 是唯一一个被 net/http 明确调用的角色，它既是请求进入你业务代码的入口，也是生命周期在你这边结束的出口。

一个最小、没有任何“设计感”的 handler 通常长这样：

package main

import (
	"fmt"
	"net/http"
)

func main() {
	http.HandleFunc("/user", userHandler)
	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func userHandler(w http.ResponseWriter, r *http.Request) {
	id := r.URL.Query().Get("id")
	w.Write([]byte("user id: " + id))
}

这段代码的问题并不是“简单”，而是什么都没限制。

解析参数、执行业务、拼响应，全混在了一起。

而 Go 并不会替你拆分这些责任，它只保证：这个函数会在请求生命周期内被调用一次。

当代码逐渐变复杂，middleware 出现的动机往往不是“优雅”，而是你开始意识到有些事情不属于具体业务。

middleware 本质上只是一个高阶函数，它做的事情非常克制：在不改变 handler 语义的前提下，包裹请求生命周期的一部分。

下面是一个最小、完整、可运行的 middleware 示例，用来打印请求耗时：

package main

import (
	"fmt"
	"net/http"
	"time"
)

func main() {
	http.Handle("/hello", timingMiddleware(http.HandlerFunc(helloHandler)))
	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func timingMiddleware(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		start := time.Now()
		next.ServeHTTP(w, r)
		fmt.Println("cost:", time.Since(start))
	})
}

func helloHandler(w http.ResponseWriter, r *http.Request) {
	time.Sleep(100 * time.Millisecond)
	w.Write([]byte("hello"))
}

middleware 并不知道“业务在干嘛”，它也不应该知道。

它只关心：请求开始了，什么时候结束，中间发生了什么通用行为。

这也是为什么 middleware 非常适合做这些事情：日志、鉴权、限流、trace、注入 request-scoped 的数据。

它们共同的特征是：它们横跨请求生命周期，但不拥有业务含义。

到了 service 这一层，视角会发生一个非常重要的变化。

service 并不知道 HTTP，也不应该知道。

它拿到的，应该只是一个 context，和一些已经被“解释过”的参数。

package main

import (
	"context"
	"fmt"
	"net/http"
)

func main() {
	http.HandleFunc("/greet", greetHandler)
	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func greetHandler(w http.ResponseWriter, r *http.Request) {
	name := r.URL.Query().Get("name")
	if name == "" {
		name = "world"
	}

	result := greetService(r.Context(), name)
	w.Write([]byte(result))
}

func greetService(ctx context.Context, name string) string {
	_ = ctx // 这里暂时不使用，只是明确服务运行在请求上下文中
	return "hello " + name
}

在这里，handler 的职责变得非常清楚：把 HTTP 世界里的东西，翻译成业务世界能理解的形式。

而 service 的职责也随之清晰起来：在一个明确的上下文里，完成一件业务上的事。

这条分界线其实非常“冷静”：

handler 关心协议、参数、状态码、响应格式
service 关心业务规则、数据一致性、流程完整性
middleware 只关心请求这件事本身的通用横切面

如果你把 service 写成“还能访问 http.Request 的函数”，那其实是在否认请求生命周期的边界；

如果你把业务判断塞进 middleware，那是在把生命周期管理和业务语义搅在一起。

慢慢看下来你会发现，Go 并没有强迫你采用这套分层，但它用非常原始的接口设计，把问题摆在你面前：HTTP 请求只会在 handler 这一层真实存在。

所有其他层级，要么是在请求外（比如异步任务），要么只是借用了请求的生命周期（通过 context）。

所以对我来说，handler / middleware / service 的边界，并不是“最佳实践”，而是一种对现实的尊重：请求有生命周期，而职责分离，只是我们对这个生命周期做出的最诚实的划分。

60. request 级资源的创建与释放

当前问题存在示例代码，可以前往GitHub查看

这一节其实是前面两节的自然延伸。

当你真正接受了“HTTP 请求是有明确生命周期的”这件事之后，下一个绕不开的问题就是：有哪些东西，应该只活在这一次请求里。

也就是所谓的 request 级资源。

在 PHP 的世界里，请求级资源往往是“顺手就有的”：全局变量、超全局数组、请求结束时的自动回收，让你很少需要主动思考“释放”这件事。

而在 Go 里，一旦你开始并发、开始复用进程，这个问题就变得不可回避。

最典型的 request 级资源，其实就是 context.Context 本身。

它不是资源的载体，而是资源生命周期的信号源。

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"
)

func main() {
	http.HandleFunc("/ctx", handler)
	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func handler(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()

	result := doWork(ctx)
	w.Write([]byte(result))
}

func doWork(ctx context.Context) string {
	select {
	case <-time.After(2 * time.Second):
		return "done"
	case <-ctx.Done():
		return "canceled"
	}
}

这里没有任何“释放代码”，但释放已经发生了：

当请求结束，ctx.Done() 被关闭，所有监听它的下游逻辑都会知道——这次请求不在了。

在我刚开始学 Go Web 的时候，很容易把注意力放在“怎么创建资源”上，却忽略了一个更重要的问题：是谁负责告诉这些资源：你该结束了。

数据库连接是一个非常容易踩到这个问题的地方。

假设我们在 handler 里，为每个请求打开一个数据库连接：

func handler(w http.ResponseWriter, r *http.Request) {
	db, _ := sql.Open("mysql", "dsn")
	defer db.Close()

	// 使用 db
}

这段代码看起来“有释放”，但它在语义上其实并不对。

sql.DB 在 Go 里是一个连接池，而不是一次连接。把它当成 request 级资源去创建和关闭，本身就是对生命周期的误判。

这件事反过来说明了一个原则：是不是 request 级资源，不取决于“是不是在 handler 里创建的”，而取决于“是否应该随请求结束而失效”。

真正典型的 request 级资源，往往是这些东西：

请求级的超时、取消信号（context）
一次业务流程中临时构建的对象
绑定在请求上的 tracing / logging 信息
必须在请求结束前完成或放弃的 I/O 操作

比如一个带超时的下游调用：

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"
)

func main() {
	http.HandleFunc("/timeout", handler)
	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func handler(w http.ResponseWriter, r *http.Request) {
	ctx, cancel := context.WithTimeout(r.Context(), time.Second)
	defer cancel()

	result := callService(ctx)
	w.Write([]byte(result))
}

func callService(ctx context.Context) string {
	select {
	case <-time.After(2 * time.Second):
		return "ok"
	case <-ctx.Done():
		return "timeout"
	}
}

这里的 cancel() 就是一次非常明确的释放行为。

不是释放内存，而是释放继续占用时间和资源的资格。

同样的思路也适用于文件、网络请求、stream 之类的资源。

如果它们的存在意义只服务于当前请求，那释放时机就应该和请求生命周期绑定。

一个常见的危险信号是：request 级资源被 goroutine 带出了 handler。

func handler(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()

	go func() {
		// 这里还在使用 ctx
		doSomething(ctx)
	}()

	w.Write([]byte("ok"))
}

从代码上看它是“合法的”，但从生命周期上看，它已经开始模糊边界了。

如果这是一个必须完成的任务，它就不应该绑定在 request 上；

如果它可以被放弃，那它就不应该假装自己还属于这次请求。

慢慢你会发现，在 Go Web 里，所谓的资源管理，并不只是 defer Close() 这么简单。

它更像是在反复问自己一个问题：这件东西，有没有理由活得比一次 HTTP 请求更久？

如果答案是否定的，那它就应该被显式地创建在请求内，并且明确地随着请求结束而失效；

如果答案是肯定的，那它就不应该被包装成 request 级资源。

对我来说，这一节并没有带来某个“技巧”，而是让我开始用生命周期来审视代码。

一旦你习惯这样看问题，很多设计上的纠结，反而会自己消失。

61. Web 中的并发模型与 goroutine 数量控制

当前问题存在示例代码，可以前往GitHub查看

这一节其实是整个「生命周期意识」里最容易被误解、也最容易被滥用的一部分。

因为在 Go 里，并发写起来实在太轻松了，轻松到你很容易忘记自己到底启动了多少 goroutine，它们又活在什么生命周期里。

在 Web 场景下，理解并发模型的第一步，是承认一个看起来很“废话”的事实：HTTP 请求本身已经是并发的。

net/http 在接收到请求时，就已经为每个请求分配了独立的 goroutine。也就是说，当你的 handler 被调用时，你已经站在并发执行的上下文中了。

package main

import (
	"fmt"
	"net/http"
	"time"
)

func main() {
	http.HandleFunc("/work", handler)
	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func handler(w http.ResponseWriter, r *http.Request) {
	time.Sleep(1 * time.Second)
	fmt.Println("request done")
	w.Write([]byte("ok"))
}

同时访问 /work 多次，你会发现这些请求是并行完成的。

这意味着一个非常重要的前提：大多数 Web handler 根本不需要再主动开启 goroutine。

刚从 PHP 转过来的时候，我很容易把 goroutine 当成“异步工具”，一看到耗时操作，就下意识地想 go func()。

但在 Web 请求里，这种直觉往往是错的。

如果你在 handler 里写出这样的代码：

func handler(w http.ResponseWriter, r *http.Request) {
	go doSomething()
	w.Write([]byte("ok"))
}

表面上看，这是“提升性能”；

但从生命周期角度看，这段代码已经做了一个非常明确的切割：你主动让一部分逻辑脱离了 HTTP 请求。

如果 doSomething 和这次请求强相关，那你其实是在逃避请求的生命周期；

如果它不再重要，那你就需要为它建立一个新的生命周期，而不是“顺手丢进 goroutine”。

真正合理的并发，往往发生在请求内部，而不是请求之外。

比如一次请求中，需要并行调用两个下游服务：

package main

import (
	"context"
	"fmt"
	"net/http"
	"sync"
	"time"
)

func main() {
	http.HandleFunc("/multi", handler)
	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func handler(w http.ResponseWriter, r *http.Request) {
	ctx := r.Context()

	var wg sync.WaitGroup
	wg.Add(2)

	var a, b string

	go func() {
		defer wg.Done()
		a = callA(ctx)
	}()

	go func() {
		defer wg.Done()
		b = callB(ctx)
	}()

	wg.Wait()
	w.Write([]byte(a + " & " + b))
}

func callA(ctx context.Context) string {
	time.Sleep(500 * time.Millisecond)
	return "A"
}

func callB(ctx context.Context) string {
	time.Sleep(700 * time.Millisecond)
	return "B"
}

这里的 goroutine 数量是被请求生命周期严格包裹住的：handler 不返回，这些 goroutine 就必须结束；context 被取消，它们就应该尽快停止。

这类并发是“可控的”，因为它有明确的边界。

真正的问题，通常出现在 goroutine 数量的失控上。

Web 服务的并发量，本身就等于同时活跃的请求数。

如果你在每个请求里，再无条件启动多个 goroutine，那最终的 goroutine 数量会变成：请求数 × 每个请求的 goroutine 数

这个乘法关系，往往是在压测或线上才暴露出来的。

一个非常朴素但有效的控制方式，是用显式的并发上限，来约束请求内的 goroutine：

package main

import (
	"fmt"
	"net/http"
	"time"
)

var sem = make(chan struct{}, 10)

func main() {
	http.HandleFunc("/limit", handler)
	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func handler(w http.ResponseWriter, r *http.Request) {
	sem <- struct{}{}
	defer func() { <-sem }()

	time.Sleep(500 * time.Millisecond)
	w.Write([]byte("ok"))
}

这里没有任何“高深技巧”，只是明确告诉系统：同一时间，最多允许 10 个请求进入这个逻辑。

你会发现，Go 提供的并发原语并不帮你“自动做对”，它们只是让你无法再忽视并发的存在。

慢慢理解下来，我对 Go Web 并发模型的看法也发生了变化：goroutine 不是性能工具，而是生命周期工具。

它让你可以非常精确地描述：哪些逻辑应该并行，哪些必须收敛，哪些不该再继续存在。

一旦你开始用这种视角看代码，“goroutine 要不要开”“开几个”“什么时候结束”，这些问题反而会变得清楚很多。

到这里，其实「Go Web 中的生命周期意识」这一章也就自然收束了。

请求的开始、职责的边界、资源的生死、并发的收敛，讲的始终是同一件事：你是否真的尊重了一次 HTTP 请求的存在范围。

十四、工程化：写“可长期维护的 Go 服务”

62. internal / pkg 的设计目的

第一次看到 Go 项目里同时出现 internal 和 pkg 的时候，我的直觉其实是困惑的。

它们看起来都像是在“放业务代码”，也不像 MVC 那样有明确的角色划分，如果从 PHP 的习惯来看，这更像是人为增加目录层级。

但慢慢看下来我意识到，internal / pkg 并不是在解决“代码怎么组织得好看”，而是在解决一个更工程化的问题：哪些代码允许被依赖，哪些代码不允许被依赖。

在 PHP 里，这件事通常是靠“约定”和“自觉”完成的。

比如你心里知道某个目录只是内部实现细节，但语言和工具层面并不会阻止别人 use 它；最多是靠文档、命名、或者 review 时提醒。

但 Go 把这件事直接变成了编译期规则。

internal 的核心设计目的只有一个：限制包只能被特定范围内的代码导入。

规则本身非常简单：如果一个包位于 internal/xxx 下，那么只有 internal 的父目录及其子目录，才能 import 它。

这个限制不是约定，而是写进了 go build 的规则里，违反就直接编译失败。

比如一个最小的结构：

myapp/
├── go.mod
├── internal/
│   └── auth/
│       └── auth.go
└── cmd/
    └── server/
        └── main.go

auth.go 内容很简单：

package auth

func Check() string {
	return "ok"
}

cmd/server/main.go：

package main

import (
	"fmt"
	"myapp/internal/auth"
)

func main() {
	fmt.Println(auth.Check())
}

这个是可以正常编译运行的，因为 cmd/server 仍然在 myapp 这个模块路径之下，满足 internal 的可见性规则。

但如果你在另一个模块里这么写：

package main

import "myapp/internal/auth"

func main() {
	auth.Check()
}

编译器会直接报错，明确告诉你：你无权导入这个 internal 包。

这一步对我冲击挺大的，因为它意味着： “这是内部实现”不再只是态度问题，而是边界问题。

也就是说，internal 并不是“私有代码”，而是“明确拒绝外部依赖的代码”。

它在设计层面就在告诉未来的维护者：这里面的东西，随时可能改、可能删、可能重构，不对外承担稳定性责任。

理解了这一点之后，再看 pkg，反而清楚多了。

pkg 并不是一个语法或编译层面的概念，它完全是社区约定。

但这个约定背后的意图和 internal 是对称的：如果你把代码放进 pkg ，那基本等于在说：这是一组打算被别人依赖的包。

也就是说：

internal：我明确不希望你用
pkg：我已经默认你可能会用

这并不意味着 pkg 里的代码一定“完美”或“稳定”，而是它在工程语义上承担了依赖入口的角色。你在这里改一个函数签名，心理预期就应该是：可能会影响模块外的调用者。

从这个角度看，internal / pkg 更像是一种依赖方向的标注系统，而不是目录分类技巧。

还有一个我后来才意识到的点：internal 实际上是在强迫你把“实现细节”聚集起来。

因为一旦你开始用 internal，你就会自然地去问自己一句话：这个包，是真的需要被模块外使用吗？

很多在 PHP 项目里“顺手就 public 了”的东西，在 Go 里一旦放进 internal，就会变成一个清晰的边界。这种边界不是给编译器看的，而是给未来的自己和团队看的。

63. 依赖方向与反向依赖的处理

在理解了 internal / pkg 之后，我才意识到一个之前被我忽略的问题：边界一旦存在，依赖方向就不再是随意的了。

在很多 PHP 项目里，依赖关系往往是“哪里用得到就直接引”。

业务代码依赖基础组件是常态，基础组件偶尔为了“方便”，也会反过来引用一点业务逻辑，只要不出事，项目依然能跑。这种结构在短期内并不会暴露明显问题。

但在 Go 的工程化语境下，这种“互相方便一下”的做法，很快就会让你感觉到不对劲。

Go 项目里，一个默认且非常强的约束是：依赖应该是单向的，而且方向是稳定的。

这个“稳定”并不是说永远不变，而是说：你应该能清楚地说出，哪些层是“被依赖者”，哪些层是“依赖者”。

一个常见的直觉是：

越底层、越通用的代码，越应该少依赖别人
越靠近业务入口的代码，越应该承担“组装”的职责

如果画成一条方向线，那大致是：main / cmd → 业务层 → 领域或服务层 → 基础设施

问题恰恰出在这里：现实项目里，总会出现“反着用更顺手”的时刻。

比如，一个通用的组件在内部，突然需要知道“当前用户是谁”；

或者一个基础库，想直接打业务日志、发业务事件；

再或者，一个 domain 包想直接操作数据库连接池。

从写代码的角度看，这些都很自然。

但从依赖方向看，它们在做同一件事：反向依赖。

在 Go 里，反向依赖几乎一定会把你逼进死角。

最直观的表现就是：

import 循环
internal 边界被打破
或者为了“解决问题”，开始把东西随便往上挪

而 Go 对 import 循环是零容忍的，一行情面都不讲。

这时候我才慢慢理解，Go 并不是在“限制你写代码”，而是在强迫你正视依赖关系本身。

那反向依赖怎么处理？

Go 社区里最常见、也最朴素的解法，其实只有一个核心思想：不要让下游知道上游的具体实现，而是只知道抽象。

而这个“抽象”，在 Go 里往往不是类，也不是框架，而是一个非常轻量的接口。

举一个极小的例子。

假设有一个内部包，需要记录日志，但它不应该依赖具体的日志实现：

// internal/service/service.go
package service

type Logger interface {
	Info(msg string)
}

type Service struct {
	logger Logger
}

func New(l Logger) *Service {
	return &Service{logger: l}
}

func (s *Service) Do() {
	s.logger.Info("doing something")
}

这个 service 包只依赖一个“行为约定”，而不是 zap、logrus 或任何具体库。

真正的日志实现，放在更外层去做：

// cmd/server/main.go
package main

import (
	"myapp/internal/service"
)

type StdLogger struct{}

func (StdLogger) Info(msg string) {
	println(msg)
}

func main() {
	svc := service.New(StdLogger{})
	svc.Do()
}

这里依赖方向是清晰的：

service 不知道“谁在用它”
main 负责把具体实现“注入”进去
依赖永远是从外向内流动的

这件事在 PHP 里也能做，但往往是靠约定、靠文档、靠经验；

而在 Go 里，它几乎是被 import 规则和工程实践“逼”出来的。

更有意思的是，当你真的开始这样拆依赖时，会发现一个变化：很多你以为“必须反向依赖”的需求，其实只是因为边界没想清楚。

一旦你承认“某些代码只能被依赖、不能主动依赖”，你就会自然开始思考：

这个信息，是不是应该由调用者提供？
这个行为，是不是应该由外层来决定？
这个包，是不是其实站在了错误的层级？

到这里，我对“依赖方向”的理解，已经不再是架构图里的箭头，而更像是一种持续存在的工程意识：每写一个 import，我都应该知道它意味着什么。

而 Go 做的事情，只是把“想不清楚就先写”的空间，压缩得非常小。

64. 配置管理（viper）与环境区分

在开始用 Go 写服务之前，我对“配置”的理解其实非常工具化：要么是 .env，要么是几个 config.php，不同环境加载不同文件，能跑就行。配置更多像是一种“启动参数的集合”，而不是工程结构的一部分。

但在 Go 的工程语境里，当你已经刻意维护了依赖方向之后，配置会变成一个绕不开的问题：谁有资格读取配置？谁不应该知道配置来自哪里？

如果你已经接受了“内部包不应该反向依赖外部实现”，那一个很自然的结论是：internal 里的业务代码，不应该自己去读环境变量、配置文件或远程配置中心。

原因并不是“这样写不好看”，而是：一旦这么做，它就偷偷引入了一个新的外部依赖，而且这个依赖几乎是不可控的。

比如下面这种代码，在 PHP 里非常常见，在 Go 里却会让人越来越不安：

func NewService() *Service {
	timeout := os.Getenv("TIMEOUT")
	// ...
}

表面看没什么问题，但实际上发生了几件事：

这个包开始依赖“当前运行环境”
它变得难以测试
它无法复用在不同启动方式下
你已经说不清它到底需要哪些配置

当你真的开始把“依赖方向”当成一条硬规则来对待时，配置就会被自然地推到最外层，也就是启动入口附近。

这正是 viper 出现的位置。

viper 本身并不神奇，它做的事情非常朴素：把“配置从哪里来”这件事统一收敛起来。

文件、环境变量、命令行参数、默认值——viper 负责把它们揉成一份“最终配置”，而不是让这些细节散落在各个业务包里。

一个最小的例子可能是这样：

// cmd/server/main.go
package main

import (
	"fmt"

	"github.com/spf13/viper"
)

type Config struct {
	Port int
	Env  string
}

func loadConfig() (*Config, error) {
	viper.SetDefault("port", 8080)
	viper.SetDefault("env", "dev")

	viper.AutomaticEnv()

	return &Config{
		Port: viper.GetInt("port"),
		Env:  viper.GetString("env"),
	}, nil
}

func main() {
	cfg, _ := loadConfig()
	fmt.Println(cfg.Port, cfg.Env)
}

关键点不在于 viper 的 API，而在于配置只在这里被读取了一次。

接下来，无论是 service、repository 还是 domain 层，都只会接触到一个普通的 Config 结构体，而不会知道它来自文件还是环境变量。

这件事和前一节讲的“反向依赖处理”其实是同一件事的延伸：你不是在避免配置，而是在避免对配置来源的依赖。

环境区分的问题，也是在这个视角下变得清晰的。

在很多项目里，“开发 / 测试 / 生产”往往意味着三套配置文件，甚至三套逻辑分支。但当配置被集中之后，环境更多只是一种“输入条件”，而不是结构差异。

一个常见做法是，只用一个明确的 env 字段：

type Config struct {
	Env      string
	LogLevel string
	Debug    bool
}

然后在入口处做最小的判断：

if cfg.Env == "prod" {
	// 开启严格模式
}

而不是让业务代码去判断“现在是不是生产环境”。

这时候你会发现，环境区分不再是“到处 if else”，而是启动阶段的一次决策。

还有一个变化是：当配置结构是显式的，你就开始真正知道“这个服务到底需要什么才能跑起来”。

在 PHP 项目里，很多配置是“慢慢长出来的”；

但在 Go 里，当你把配置集中成一个结构体，它就天然变成了一份服务的运行契约

65. 结构化日志（zap）的使用原则

zap 是 Go 里常用的结构化日志库，它把日志从字符串输出，变成由字段组成的数据，并在性能和工程化使用上做了明确取舍。

至于 API 或性能细节，其实并不是这一节真正关心的重点。

真正让我开始认真思考日志问题的，是当我不再用 fmt.Println，而是开始使用结构化日志之后，日志本身就不再只是调试输出，而变成了一项需要被正确放置的工程能力。

如果回到前面已经形成的工程共识：依赖方向是稳定的，内部包不感知外部环境，启动入口负责组装一切外部能力，那么日志就不应该是一种“到处可用的全局工具”，而更像是一种被注入的、带上下文的依赖。

这也是我逐渐意识到的一个使用原则：zap 的 logger 本身就是一种依赖。

既然是依赖，它就应该遵守依赖方向的规则。

在入口处创建 logger，然后向内层传递，是一种非常常见的做法：

// cmd/server/main.go
logger, _ := zap.NewProduction()
defer logger.Sync()

svc := service.New(logger)

而内部包只接收它真正需要的能力：

// internal/service/service.go
type Service struct {
	logger *zap.Logger
}

func New(l *zap.Logger) *Service {
	return &Service{logger: l}
}

func (s *Service) Do() {
	s.logger.Info("doing something")
}

这里真正重要的，并不是“用了 zap”，而是：日志能力是从外部注入的，而不是在内部被隐式获取的。

这一点，和前面关于配置、依赖方向的讨论，其实是同一件事的延续。

当日志开始以这种方式存在时，我发现自己会不自觉地开始收敛日志的位置。

一个很明显的变化是：越靠近业务核心的代码，日志越应该克制。

业务代码关心的是“发生了什么”，而不是“如何被观测”。

如果一个 domain 或 service 层的方法里充满了日志调用，那它其实已经在替外部系统做观测决策了，而这些决策本来就应该留在更外层。

结构化日志在这里起到的作用，不是让日志“更复杂”，而是逼你区分两件事：事件本身，和事件的属性。

s.logger.Info(
	"user login failed",
	zap.String("user_id", uid),
	zap.String("reason", err.Error()),
)

相比拼接字符串，这种写法更像是在描述一个事件，而不是解释一段过程。一旦习惯这种方式，就会自然减少情绪化、解释性的日志，转而记录更偏事实的字段信息。

还有一个后来才逐渐清晰的原则是：不要在低层决定日志级别的语义。

比如，一个 repository 方法返回了 sql.ErrNoRows，它本身并不知道这是一个正常的业务分支，还是一个真正的异常情况。

如果它在内部直接记录 Warn 或 Error，那实际上已经替上层做了判断。

更合理的方式是：低层只负责返回结果或错误，而由真正理解业务语义的上层，来决定是否记录日志、记录到什么级别。

到这里，我对 zap 的理解已经不再是“一个高性能日志库”，而更像是：它在不断提醒你，日志是一种语义表达，而不是调试输出。你不是在“打日志”，而是在为系统留下可被理解的行为痕迹。

66. 错误、日志、trace 的协作关系

在开始同时接触错误处理、结构化日志和 trace 之后，我有过一段明显的混乱期。

同样是一次失败，有时候返回 error，有时候打日志，有时候加 trace，看起来都“说得通”，但放在一起就开始显得重复，甚至互相打架。

后来我才慢慢意识到，这三者之所以容易被混用，往往是因为没有先想清楚一个问题：它们各自是为谁服务的。

error 是最内层、也是最克制的一种表达。

它的唯一职责，是把“发生了异常”这个事实，沿着调用链向上返回。

一个 error 本身不负责被人“看到”，它只负责被处理。

这也是为什么在 Go 里，error 被设计成普通返回值，而不是异常机制。

它天然地顺着依赖方向向外传播，而不是在某个地方突然被“抛出来”。

日志则完全不同。

日志并不是为了控制流程，而是为了事后观察系统行为。

也正因为如此，它不应该无条件地和 error 绑定在一起。

一个很典型的误用，是在产生 error 的地方立刻记录日志。

这样写当然没有语法问题，但它隐含了一个假设：这个 error 一定值得被记录，而且我已经知道该以什么语义记录。

但在实际工程里，低层代码往往并不具备这样的判断能力。

一个 error 是正常分支、边界条件，还是系统异常，通常只有更上层才真正清楚。

所以在我现在的理解里，更合理的协作方式是：

error 负责表达问题
日志负责表达语义

低层返回 error，高层在“理解上下文”的地方决定是否记录日志，以及记录到什么级别。

这一点，和前一节里“不要在低层决定日志级别”的结论是完全一致的。

trace 则站在另一个维度。

如果说 error 是“点”，日志是“事件”，那 trace 更像是一条跨越多个组件的时间线。

它并不关心你在某一行代码里做了什么，而关心一次请求从进入系统开始，到离开系统为止，经历了哪些节点。

也正因为这个定位，trace 通常既不由业务代码主动创建，也不由业务代码主动结束。

它更像是一种运行时上下文，被创建于入口，被传递，被使用，而不是被“控制”。

这也是为什么在 Go 里，trace 往往和 context.Context 一起出现。

func Handle(ctx context.Context) error {
	// ctx 内部可能已经携带 trace 信息
	return doSomething(ctx)
}

这里的 ctx 并不是用来存业务数据的，而是用来携带这次调用的“观察信息” 。

业务代码并不需要知道 trace 的具体实现，只需要把上下文继续往下传。

把这三者放在一起看，会发现一个很清晰的层次关系：

error：控制流程，向上返回
log：表达语义，在合适的层记录
trace：串联全局，跨边界观测

它们不是并列关系，也不是互相替代的工具，而是各自负责一个不同的问题维度。

当我开始按这个顺序来使用它们之后，一个变化非常明显：代码里的“重复表达”开始减少了。

我不再需要在每个 error 产生的地方都打日志；

也不需要用日志去模拟一次请求的完整生命周期；

更不会用 error 去承载“调试信息”。

到这里，这一整章“可长期维护的 Go 服务”，对我来说就不再是某几条零散的最佳实践，而是一组可以互相支撑的工程约束：边界清晰，依赖单向，外部因素集中处理，而观测能力各司其职。

这些东西单独看都不复杂，但一旦连在一起，就会不断逼你把系统“想清楚之后再写出来”。

十五、从 PHP 项目到 Go 项目的思维迁移

67. 哪些 PHP 设计可以直接迁移

从 PHP 到 Go，并不是把一套设计推翻重来，而是发现：真正能迁移的，从来就不是语言技巧，而是你已经形成的工程判断。

比如分层意识。

在 PHP 项目里，即便没有严格的 DDD，也很少有人真的把「控制器里直接写 SQL」当成理想状态。

控制器负责接 HTTP、做参数校验；

服务层负责业务组合；

仓储或模型层负责数据访问。

这一点在 Go 里不仅没有被否定，反而更“显性”了：你不再靠框架约定去暗示这些层次，而是靠 package、文件结构、接口边界去把它们写出来。

本质上，思路是完全一致的，只是 Go 不帮你兜底。

还有一类是 “把变化点隔离出来” 的习惯。

在 PHP 中，你可能早就习惯：

外部接口要包一层
第三方 SDK 不要散落在业务代码里
配置集中管理，而不是到处 getenv

这些并不是 Laravel 或 Symfony 教你的，而是项目写久了自然形成的防御性设计。

到了 Go，这套东西依然成立，而且更容易“被迫坚持”：

因为没有魔术方法，乱调用会立刻变得难看
因为类型是显式的，变化会第一时间传染到调用方
因为编译期就能发现问题，你会更愿意提前把边界画清楚

你会发现：你不是在学新的设计，而是在被迫把以前模糊的设计说清楚。

再比如 “数据结构先于流程” 这个习惯。

在 PHP 中，很多时候我们是先把流程写出来，再用数组去“凑”数据结构。

但稍微复杂一点的系统，很快就会演变成：

约定好的数组 key
注释说明这个数组“长什么样”
靠经验保证大家用法一致

如果你已经写到这个阶段，那么迁移到 Go 时，其实几乎是无缝的：你只是把那些“靠注释和默契维持的结构”，变成了 struct。

Go 并没有改变你的设计方式，只是把“隐含的前提”变成了“编译器要求你说明的事实”。

还有一个很容易被忽略，但其实完全可迁移的点：对副作用的警惕。

成熟一点的 PHP 项目里，大家都会尽量避免：

方法悄悄改全局状态
隐式依赖某个单例
调用一个函数却不知道它会不会顺带做别的事

这些在 PHP 中是“自觉”，在 Go 中则几乎变成了“基本生存技能”。

你会更频繁地思考：

这个函数有没有状态
这个状态归谁管
这个改动会不会被并发放大

但这并不是 Go 才有的意识，而是你在 PHP 项目里已经形成的工程直觉，只是现在被放到了台面上。

68. 哪些 PHP 写法在 Go 中是反模式

很多 PHP 写法之所以“看起来没问题”，并不是因为它们本身多优雅，而是因为 PHP 的运行模型一直在替你兜底。

当你把这些写法原样带进 Go 时，问题不是“能不能跑”，而是“跑起来之后你还能不能控制住它”。

一个很典型的反模式是：过度依赖隐式共享状态。

在 PHP 里，我们很习惯：

全局配置随时可读
单例对象到处可用
容器里拿服务几乎没有成本

因为一次请求结束后，所有状态都会被回收，“这次改了点什么”这件事，天然是短命的。

但在 Go 里，进程是长期存在的，goroutine 是并发执行的。

当你还用“反正下一个请求就重来”的心态去写代码时，

共享状态就不再是便利，而会变成一个放大器：

一个小小的可变字段
在并发下被反复读写
问题不会立刻出现，却很难复现

这时候你会意识到：在 PHP 里被生命周期掩盖的问题，在 Go 里会被无限放大。

另一个很常见的，是用“宽松数据结构”偷懒。

PHP 里用数组承载一切信息，是一种被长期纵容的写法：

同一个数组，在不同阶段拥有不同含义
key 靠约定，而不是约束
出错时，往往只是多了一个 null

这种写法在 PHP 中不算致命，因为运行时本身就非常宽容。

但在 Go 里，如果你还试图用 map[string]interface{} 去复刻这套灵活性，

你会发现：

类型断言开始到处出现
调用方需要知道更多内部细节
错误变得延迟、分散、不可预测

这并不是 Go “不够灵活”，而是它拒绝替你兜住不确定性。

你一旦继续依赖这种宽松结构，就等于主动放弃了 Go 能提供的安全感。

还有一种反模式，来自 “把流程当作一切” 的思维。

很多 PHP 代码，本质上是“脚本式”的：

从上到下
边查数据边处理
顺手在中间修改点状态

在 Web 请求模型下，这种写法非常自然，而且往往足够快、足够清晰。

但当你在 Go 中开始写并发、写异步、写长期运行的任务时，这种“流程即设计”的代码会迅速变得脆弱：

状态散落在流程的各个角落
很难拆分、复用或并发执行
一旦中途失败，回滚和补偿几乎无从谈起

你会慢慢发现，在 Go 里，流程只是结果，结构和边界才是设计本身。

还有一个经常被忽略的点：用“约定”代替约束。

在 PHP 项目中，我们很习惯靠：

文档说明参数怎么传
注释约定返回值含义
Code Review 来保证大家“别乱用”

这在 PHP 里是现实选择，因为语言本身给不了你更多工具。

但在 Go 里，如果你仍然选择只靠约定，而不通过：

明确的类型
明确的接口
明确的错误返回

那你其实是在刻意绕开 Go 的设计初衷。

不是 Go 强迫你这么写，而是你一旦不这么写，就失去了它存在的意义。

69. Go 中“复制数据”往往比“共享数据”更安全

在 Go 里，共享数据的危险并不是“会出错”，而是“你很难证明它没出错” 。

当一个 struct、一个 map、一个 slice 被多个 goroutine 持有时，哪怕你“逻辑上觉得没问题”，你也需要开始思考一连串以前不需要思考的事情：

谁负责写？
什么时候写？
读的时候是否可能被改？
这个假设未来还成立吗？

问题在于，这些假设本身不会被代码显式表达出来。

它们存在于你的脑子里，而不是存在于程序里。

于是你会慢慢发现一种非常反直觉的现象：多拷贝几份数据，代码反而更简单、更安全。

在 PHP 里，复制往往意味着性能浪费，而共享看起来是理所当然的。

但在 Go 里，很多时候你复制的并不是“巨大成本”，而是在用内存换取一种非常确定的语义：

这份数据只属于当前 goroutine
它的生命周期清晰
不会被别人悄悄改掉

一旦你接受了这个前提，很多并发问题会自动消失，而不是靠锁去“压住”。

你可能会注意到，Go 的很多设计，都在暗示你偏向复制而不是共享。

比如：

函数参数默认就是值传递
struct 是可以直接拷贝的
channel 更鼓励你传“数据快照”，而不是传指针
官方示例里，锁往往是最后的选择，而不是默认选项

这些并不是偶然的 API 设计，而是在持续地引导你：把数据的所有权想清楚，比把锁写对更重要。

对 PHP 开发者来说，这其实是一种所有权意识的觉醒。

在 PHP 中，变量的“归属感”是很弱的：反正请求结束就没了，反正下一个请求是全新的世界。

而在 Go 里，你会被迫回答这样的问题：

这份数据现在属于谁？
它会被传给谁？
我是否还需要关心它之后的变化？

当你无法清晰回答这些问题时，复制，反而成了一种非常诚实的做法：我不打算管理共享，那就干脆不共享。

这也是为什么你会慢慢形成一种偏好：

小数据，直接复制
明确边界，传值
只有在“确实需要共享状态”时，才引入锁或同步原语

这不是性能至上的选择，而是一种把复杂度控制在可理解范围内的选择。

70. 典型 PHP 模块的 Go 化重构思路

如果拿一个典型的 PHP 模块来看，通常会长得很“自然”：

一个 Service 类
里面挂着好几个依赖（DB、缓存、HTTP 客户端）
方法里既有业务判断，也顺手做了数据访问和状态修改

在 PHP 的请求模型下，这种模块往往没有明显问题，因为它的职责边界是由“请求生命周期”隐式保证的。

但当你把它搬到 Go 中时，第一个遇到的不是语法问题，而是一个更根本的问题：这个模块到底是“状态的拥有者”，还是“逻辑的执行者”？

一个常见的 Go 化重构起点，是先拆掉“隐式上下文” 。

在 PHP 中，Service 往往默认可以：

直接用全局配置
直接访问容器里的其他服务
直接假设某些前置状态已经存在

而在 Go 中，这些“默认存在”的东西会变得非常模糊。

于是重构的第一步，通常不是拆业务，而是：

把依赖全部显式化
通过构造函数注入
用参数而不是环境传递上下文

你会发现，很多你以为是“业务复杂”的地方，其实只是依赖不清晰。

接下来，一个很典型的变化是：把“做事情的人”和“存数据的人”分开。

在 PHP 中，一个 Service 里既：

决定“要不要做”
又知道“数据怎么拿”
还顺便“把状态存回去”

这种聚合在 PHP 中很常见，也不算坏。

但在 Go 中，你会更倾向于：

Repository 只负责数据访问
Service 只负责编排业务规则
数据结构本身尽量保持“被动”

这并不是为了“层次感好看”，而是为了让每一部分在并发和测试中都更容易被控制。

再往下，你会开始重构函数的形态。

很多 PHP 方法的典型特征是：

入参少
内部读取大量外部状态
返回值模糊（成功 / 失败靠约定）

在 Go 化过程中，这类方法往往会被改造成：

入参明确、甚至略显啰嗦
所需信息全部通过参数传入
返回 (result, error)，而不是“顺带改变点什么”

这种改变一开始会让人觉得“写起来好累”，但它带来的一个直接好处是：每个函数都更接近一个独立、可推理的单元。

还有一个非常实际的变化点，是模块边界的确定方式。

在 PHP 中，模块边界往往靠：

目录结构
命名约定
框架的自动加载规则

而在 Go 中，package 本身就是边界。

你不能随意跨包访问未导出的东西，这会迫使你认真思考：

哪些是模块的“对外承诺”
哪些只是内部实现细节
哪些结构根本不应该被别人看到

于是，重构的结果往往不是“代码更多了”，而是暴露出来的东西更少了。

如果把整个 Go 化重构的过程压缩成一个思路，其实可以是这样：

先显式化依赖
再明确数据的所有权
最后才是拆分和组织业务逻辑

这和“把 PHP 代码翻译成 Go”是完全不同的路线。

十六、部署与稳定性

71. Go 程序的启动与退出流程

一开始我并没有把 Go 程序当成一个“有生命周期的进程”来看。

在我的直觉里，它更像是：启动 → 执行 → 结束，只是执行时间变长了而已。

直到我真的开始思考部署，这个理解才慢慢发生偏移。

一个最简单的 Go 程序是这样的：

package main

import "fmt"

func main() {
	fmt.Println("hello world")
}

这段代码看起来几乎没有任何信息量，但它其实已经隐含了一件事：进程一启动，就会一路执行到 main() ，中间没有可以被忽略的阶段。

如果我加上一点初始化代码：

func init() {
	fmt.Println("init something")
}

func main() {
	fmt.Println("start service")
}

那么启动顺序是确定的，而且完全写在代码里。

依赖包加载完成后，init 会被调用，随后进入 main()。

这里不存在“框架接管启动流程”的感觉，程序是直接面对操作系统开始运行的。

这件事让我慢慢意识到：Go 程序的启动逻辑，几乎等同于这个进程真实发生的启动行为。

你在 main 里写了什么，进程启动时就做了什么；你没有写的事情，系统也不会替你补上。

这种“直接感”在退出时同样明显。

在 Go 里，main() 函数一旦返回，整个进程就结束了。没有一个默认的“善后阶段”，也没有一个全局的退出回调。比如下面这段代码：

func main() {
	go func() {
		for {
			fmt.Println("working...")
		}
	}()

	fmt.Println("main exit")
}

main 打印完 "main exit" 之后，进程立刻退出，后台 goroutine 会被直接终止。

它们并不会因为“还在工作中”而获得额外的存活时间。

这件事一开始会让我有点不适应，但后来反而觉得它很诚实。

Go 并不会假装帮你处理好退出时的复杂情况，它只提供一个非常清晰的规则：main 结束，世界就结束。

这也意味着，defer、资源释放、连接关闭这些事情，只有在你明确设计退出路径时才会发生。Go 不会在进程退出前偷偷帮你“收拾一下”。

慢慢地，我开始把 Go 程序理解为一段连续存在的时间，而不是一连串被触发的执行片段。

程序从启动那一刻起，就已经作为一个长期存在的进程站在系统里；而当它退出时，也意味着你承认这段时间该被完整地终结。

也正是在这种视角下，“如何退出”才第一次变成一个值得认真对待的问题，而不只是 return 一下那么简单。

后面再去看信号、优雅关闭、systemd，反而变成了顺理成章的事情。

72. 信号处理与优雅关闭

当我意识到 main 一结束，整个进程就会被毫不犹豫地终止时，“退出”这件事开始变得不那么简单了。

因为在真实环境里，程序几乎从来不是自己决定要不要退出的。

更多时候，退出是被通知的。

比如端口要被释放、服务要重启、机器要关机。

对程序来说，这些都不是逻辑错误，而是外部世界在告诉你：现在该停下来了。

在 Go 里，这种“通知”通常以信号的形式出现。

go run main.go

当我在终端里按下 Ctrl+C，进程并不是“正常 return 了”，而是收到了一个来自操作系统的信号。

如果程序什么都不做，那么默认行为只有一个：立刻退出。

这时候我才慢慢意识到一个事实：所谓的“优雅关闭”，并不是 Go 自动提供的能力，而是一种你需要主动参与的协议。

如果我什么都不写，Go 程序对信号的态度其实非常简单：

func main() {
	select {}
}

这个程序看起来可以一直运行，但当收到退出信号时，它会直接被终止，没有任何过渡，也没有任何清理逻辑。

它并不知道“现在退出意味着什么”。

于是，处理信号这件事就变成了：在进程被强制终止之前，给自己一个“知道要结束了”的机会。

在 Go 里，这个机会通常是这样拿到的：

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()

<-ctx.Done()
fmt.Println("收到退出信号，准备关闭")

这里让我印象很深的一点是，Go 并没有引入一套“特殊的退出生命周期”，而是把信号直接映射成了 context。

退出不再是一个异类事件，而是一次上下文的取消。

当我开始用这种方式看待信号时，思路会变得非常统一：

启动服务时创建上下文；
收到信号时取消上下文；
正在工作的 goroutine 感知到取消，自行决定如何收尾。

比如这样：

go func(ctx context.Context) {
	for {
		select {
		case <-ctx.Done():
			fmt.Println("worker exit")
			return
		default:
			// do work
		}
	}
}(ctx)

这里并没有“强制终止”的感觉。goroutine 是自己意识到“该结束了”，而不是被突然杀掉。

这也是我后来理解“优雅”的方式：不是程序永远不出问题，而是当问题不可避免地发生时，它有一条清晰、可预测的退出路径。

这套机制看起来并不复杂，但它带来的变化很明显。

退出不再是 main 的一个 return，而是一个会向整个系统扩散的信号；

关闭不再是瞬间发生的事情，而是一个可以被观察、被等待的过程。

当我把信号、上下文和 goroutine 放在同一个时间线上看时，Go 的设计开始显得非常克制。

它不试图帮你“自动优雅”，只是提供了一套足够简单的工具，让你明确地写下：什么时候该停、谁需要知道、以及要怎么停。

也正是因为这种克制，后面再去看 systemd 对 Go 服务的管理方式时，我反而觉得它们是天然对齐的，而不是两套勉强拼在一起的机制。

73. systemd 部署 Go 服务的实践

在真正把 Go 服务放到 systemd 下面运行之前，我对 systemd 的理解其实非常工具化：写个 unit 文件，能跑起来就行。

但当前面已经把“启动”“退出”“信号”这些事情想清楚之后，再回头看 systemd，视角会发生明显变化。

systemd 并不是在“托管你的代码”，它只是在管理一个进程。

而 Go 写出来的服务，本身就非常像 systemd 期待的那种进程。

一个最基础的 unit 文件大概是这样的：

[Unit]
Description=My Go Service
After=network.target

[Service]
ExecStart=/usr/local/bin/my-service
Restart=on-failure

[Install]
WantedBy=multi-user.target

第一次看到这种配置时，我会下意识地找一些“生命周期钩子”，比如启动前、关闭后之类的东西。

但 systemd 的思路其实很简单：它只关心进程是否存在，以及它是如何退出的。

ExecStart 启动进程，进程活着，服务就活着；

进程退出，systemd 只根据退出结果来决定下一步要不要重启。

这时候前面那些关于 Go 启动与退出的理解，开始变得非常实用。

因为对 systemd 来说，Go 程序的 main() 就是整个服务的生命线。

当 systemd 需要停止服务时，它不会“调用你的关闭函数”，而是向进程发送信号。

如果你的 Go 程序已经处理了这些信号，那么 systemd 发出的停止请求，就会自然地变成一次可控的退出流程。

[Service]
ExecStart=/usr/local/bin/my-service
ExecStop=/bin/kill -SIGTERM $MAINPID

但实际上，即使你不显式写 ExecStop，systemd 默认发送的也是类似的终止信号。

systemd 和 Go 之间的“对话语言”，从头到尾只有信号。

这也是为什么在 Go 服务里处理信号显得如此重要。

不是为了“代码优雅”，而是为了让外部的进程管理工具，能够准确地理解你的状态。

当 Go 程序在收到信号后，选择有序地关闭 goroutine、释放资源、最终退出时，systemd 看到的只是一个“正常结束的进程”。

而这对于 systemd 来说，已经足够了。

我后来才意识到一件事：systemd 并不需要你告诉它“我已经优雅关闭了”，它只需要看到进程在合理时间内退出。

如果你的程序迟迟不退出，systemd 会认为它“卡住了”；

如果你的程序直接被杀死，systemd 会认为它“异常结束”。

剩下的判断，全部来自于你对进程退出路径的设计。

也正因为这种关系非常直接，Go 服务在 systemd 下反而显得很轻松。

没有适配层，没有特殊协议，也不需要额外的运行时支持。

Go 程序只是安静地作为一个进程存在，而 systemd 则用它最擅长的方式看护这个进程。

当我把这些细节连在一起看时，会有一种很明确的感觉：这并不是“systemd 很适合 Go”，而是 Go 写出来的服务，本身就符合 systemd 对服务的想象。

74. 为什么 Go 天然适合做常驻服务

当我把 Go 程序的启动、退出、信号处理，以及 systemd 的行为放在同一条时间线上之后，“Go 适合做常驻服务”这件事反而不再像一句评价，而更像一个结果。

Go 写出来的程序，本身就是一个非常完整的进程。

它从启动那一刻起，就已经准备好长期存在，而不是等待某个外部事件来“激活自己”。

main() 不只是一个入口函数，它几乎等同于整个服务的生命周期。

你在这里初始化资源、启动 goroutine、监听端口，也在这里等待退出信号、关闭通道、结束进程。

服务的开始和结束，全部发生在你看得见的代码里。

这种模型对常驻服务来说非常自然。

因为常驻服务关心的，本来就不是“某一次请求”，而是一段持续存在的时间。

Go 对并发的处理方式，也让这种“长期存在”变得轻量。

goroutine 不需要你为它们分配明确的线程资源，它们更像是一种随时可以启动、随时可以结束的工作单元。

这让服务在运行过程中可以不断变化形态，而不必承担过高的管理成本。

更重要的是，Go 对“退出”的态度非常明确。

进程什么时候结束，不是由框架决定的，而是由你写下的退出路径决定的。

信号不会被包装成复杂的生命周期事件，而是直接转化为上下文的取消。

常驻服务最怕的，其实不是崩溃，而是状态不清楚。

不知道自己现在是不是还在工作，也不知道外部世界希望它什么时候停下来。

Go 在这一点上显得非常克制。

它不试图替你隐藏复杂性，只是提供一套足够简单、足够稳定的抽象，让你把这些状态写清楚。

当 systemd 把 Go 服务当成一个普通进程来看待时，Go 也正好是以一个普通、但非常自洽的进程在运行。

双方不需要额外约定，也不需要特殊照顾。

回过头来看，我会发现：Go 并不是“为了做服务而设计的语言”，但它对进程、并发、退出的理解，刚好与常驻服务的需求高度重合。

所以这种“天然适合”，并不是来自某个单一特性，而是来自一种一致的设计取向：程序从启动开始就认真地存在着，并且对自己的结束负责。

十七、并发型实战项目

75. 并发 webhook 接收与处理服务

当前问题存在示例代码，可以前往GitHub查看

package main

import (
	"encoding/json"
	"fmt"
	"math/rand"
	"net/http"
	"sync"
	"time"
)

// WebhookPayload 定义接收的数据结构
type WebhookPayload struct {
	Event     string         `json:"event"`
	Timestamp time.Time      `json:"timestamp"`
	Data      map[string]any `json:"data"`
	Signature string         `json:"signature"`
}

// WebhookProcessor 表示一个典型的“生产者-消费者”模型：
// HTTP 层作为生产者，worker 池作为消费者。
// 这个结构体本身并不关心 HTTP，只关心如何并发、安全地处理任务。
type WebhookProcessor struct {
	// queue 是任务缓冲队列，用来承接 HTTP 请求与后台处理之间的速率差
	// 使用带缓冲的 channel，可以避免 webhook 高峰期直接把服务压垮
	queue chan WebhookPayload

	// workers 表示 worker goroutine 的数量
	// 在这个模型里，它同时也代表了最大并发处理能力
	workers int

	// wg 用来等待所有 worker 正常退出
	// 这使得 Stop() 可以是一个“阻塞直到完全停止”的操作
	wg sync.WaitGroup

	// stopChan 用来广播“停止信号”
	// 一旦关闭，所有 worker 都应该开始走退出路径
	stopChan chan struct{}

	// processing 作为一个信号量（semaphore），用于限制同时处理的任务数
	// 在本例中，由于 worker 数量已经限制了并发度，这个 channel 实际上是演示用途
	processing chan struct{}
}

// NewWebhookProcessor 创建新的处理器
func NewWebhookProcessor(workers int, queueSize int) *WebhookProcessor {
	return &WebhookProcessor{
		queue:      make(chan WebhookPayload, queueSize),
		workers:    workers,
		stopChan:   make(chan struct{}),
		processing: make(chan struct{}, workers),
	}
}

// Start 启动 worker 池。
// 每个 worker 都是一个独立的 goroutine，
// 它们会持续从 queue 中取任务，直到收到 stop 信号。
func (wp *WebhookProcessor) Start() {
	for i := 0; i < wp.workers; i++ {
		wp.wg.Add(1)
		go wp.worker(i)
	}
	fmt.Printf("启动 %d 个 worker 处理 webhook\n", wp.workers)
}

// Stop 用来通知所有 worker 停止工作，并等待它们退出。
// 这里并不会强制中断正在处理的任务，而是给 worker 一个“该结束了”的信号。
func (wp *WebhookProcessor) Stop() {
	close(wp.stopChan)
	wp.wg.Wait()
	fmt.Printf("所有 worker 已停止\n")
}

// worker 是实际执行 webhook 处理逻辑的 goroutine。
// 每个 worker 会在一个循环中等待任务或停止信号。
func (wp *WebhookProcessor) worker(id int) {
	defer wp.wg.Done()

	for {
		select {
		// 一旦 stopChan 被关闭，所有 worker 都会走到这里并退出
		case <-wp.stopChan:
			fmt.Printf("Worker %d 收到停止信号，退出\n", id)
			return

		// 从任务队列中取出一个 payload
		// 如果此时队列为空，worker 会阻塞在这里等待新任务
		case payload := <-wp.queue:
			// 通过向 processing channel 写入一个值，表示“占用一个处理名额”
			wp.processing <- struct{}{}

			fmt.Printf("Worker %d 开始处理事件: %s\n", id, payload.Event)

			// 实际的业务处理逻辑
			wp.processPayload(id, payload)

			// 释放处理名额
			<-wp.processing
		}
	}
}

// AddPayload 尝试将 webhook payload 放入处理队列。
// 这里使用非阻塞写入，是为了避免 HTTP 请求被无限期卡住。
func (wp *WebhookProcessor) AddPayload(payload WebhookPayload) error {
	select {
	case wp.queue <- payload:
		fmt.Printf("事件 %s 已加入队列\n", payload.Event)
		return nil
	default:
		// 当队列已满时，直接返回错误，由 HTTP 层决定如何响应
		return fmt.Errorf("处理队列已满")
	}
}

// processPayload 实际处理webhook的业务逻辑
func (wp *WebhookProcessor) processPayload(workerID int, payload WebhookPayload) {
	// 模拟随机处理时间
	r := rand.New(rand.NewSource(time.Now().UnixNano()))
	randomNum := r.Intn(5) + 1
	time.Sleep(time.Second * time.Duration(randomNum))
	// 打印payload
	dataJSON, _ := json.MarshalIndent(payload.Data, "", "  ")
	fmt.Printf("Worker %d 处理完成 - 事件: %s, 时间: %s\n数据: %s\n", workerID, payload.Event, payload.Timestamp.Format(time.DateTime), string(dataJSON))
}

// healthCheck 检查接口是否正常
func healthCheck(w http.ResponseWriter, r *http.Request) {
	w.Header().Set("Content-Type", "application/json")
	json.NewEncoder(w).Encode(map[string]any{
		"status": "healthy",
		"time":   time.Now().Format(time.DateTime),
	})
}

// webhookHandler 是 HTTP 层与处理器之间的“边界”。
// 它的职责非常明确：
// 1. 校验请求
// 2. 解析数据
// 3. 尝试入队
// 4. 尽快返回响应
func webhookHandler(processor *WebhookProcessor) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		if r.Method != http.MethodPost {
			http.Error(w, "只支持 POST 请求", http.StatusMethodNotAllowed)
			return
		}

		// 这里对 Content-Type 的判断是简化版本
		// 真实环境中可能需要兼容 charset 等参数
		if r.Header.Get("Content-Type") != "application/json" {
			http.Error(w, "只支持 application/json", http.StatusUnsupportedMediaType)
			return
		}

		var payload WebhookPayload
		if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
			http.Error(w, "无效的 JSON 格式", http.StatusBadRequest)
			return
		}

		// 补充一些基础字段，避免后续处理时出现空值
		if payload.Timestamp.IsZero() {
			payload.Timestamp = time.Now()
		}
		if payload.Event == "" {
			payload.Event = "未知"
		}

		// 尝试将任务交给后台处理器
		if err := processor.AddPayload(payload); err != nil {
			http.Error(w, err.Error(), http.StatusServiceUnavailable)
			return
		}

		// webhook 的最佳实践通常是“尽快确认已接收”
		w.WriteHeader(http.StatusAccepted)
		w.Header().Set("Content-Type", "application/json")
		json.NewEncoder(w).Encode(map[string]any{
			"status":  "accepted",
			"message": "webhook 已接收",
			"event":   payload.Event,
		})
	}
}

// metricsHandler 监控信息：显示队列状态
func metricsHandler(processor *WebhookProcessor) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("Content-Type", "application/json")
		json.NewEncoder(w).Encode(map[string]any{
			"queue_length":     len(processor.queue),
			"queue_capacity":   cap(processor.queue),
			"processing_count": processor.workers,
			"timestamp":        time.Now().Format(time.DateTime),
		})
	}
}

func main() {
	// 配置参数
	port := ":8080"
	workers := 5
	queueSize := 100

	// 创建webhook处理器
	processor := NewWebhookProcessor(workers, queueSize)

	// 启动worker池
	processor.Start()
	defer processor.Stop()

	// 设置http路由
	http.HandleFunc("/webhook", webhookHandler(processor))
	http.HandleFunc("/health", healthCheck)
	http.HandleFunc("/metrics", metricsHandler(processor))

	// 启动http服务
	fmt.Printf("http服务启动在: http://localhost%s\n", port)
	fmt.Println("可用端点:")
	fmt.Println("  POST /webhook - 接收webhook")
	fmt.Println("  GET  /health  - 健康检查")
	fmt.Println("  GET  /metrics - 查看队列状态")
	if err := http.ListenAndServe(port, nil); err != nil {
		fmt.Println("服务器启动失败", err)
	}

}

76. 并发执行 shell 的任务调度器

当前问题存在示例代码，可以前往GitHub查看

package main

import (
	"bufio"
	"bytes"
	"context"
	"fmt"
	"io"
	"log"
	"os"
	"os/exec"
	"os/signal"
	"strings"
	"sync"
	"syscall"
	"time"

	"github.com/fatih/color"
)

// TaskStatus 任务状态
type TaskStatus int

const (
	StatusPending   TaskStatus = iota // 0
	StatusRunning                     // 1
	StatusSuccess                     // 2
	StatusFailed                      // 3
	StatusTimeout                     // 4
	StatusCancelled                   // 5
)

func (s TaskStatus) String() string {
	switch s {
	case StatusPending:
		return "⏳ 待处理"
	case StatusRunning:
		return "🚀 运行中"
	case StatusSuccess:
		return "✅ 成功"
	case StatusFailed:
		return "❌ 失败"
	case StatusTimeout:
		return "⏰ 超时"
	case StatusCancelled:
		return "🚫 取消"
	default:
		return "❓ 未知"
	}
}

// Task 任务定义
type Task struct {
	ID           string        // 任务ID
	Name         string        // 任务名称
	Cmd          string        // 执行命令
	Args         []string      // 命令参数
	Timeout      time.Duration // 超时时间
	RetryCount   int           // 重试次数
	RetryDelay   time.Duration // 重试延迟
	MaxOutput    int           // 最大输出行数
	Env          []string      // 环境变量
	WorkDir      string        // 工作目录
	Dependencies []string      // 依赖的任务ID
}

// TaskResult 任务执行结果
type TaskResult struct {
	TaskID     string        // 任务ID
	TaskName   string        // 任务名称
	Status     TaskStatus    // 任务状态
	StartTime  time.Time     // 开始时间
	EndTime    time.Time     // 结束时间
	Duration   time.Duration // 持续时间
	ExitCode   int           // 退出code
	Output     string        // 输出内容
	Error      error         // 错误信息
	RetryCount int           // 重试次数
}

// Scheduler 调度器
type Scheduler struct {
	maxWorkers      int                    // 最大并发数
	tasks           map[string]*Task       // 所有任务
	taskResults     map[string]*TaskResult // 所有任务结果
	taskQueue       chan *Task             // 任务队列
	taskResultQueue chan *TaskResult       // 结果队列
	wg              sync.WaitGroup         // 等待组
	mu              sync.Mutex             // 读写锁
	ctx             context.Context        // 上下文
	cancel          context.CancelFunc     // 取消函数
	isRunning       bool                   // 是否正在运行
	completedTasks  map[string]bool        // 已完成任务
}

// NewScheduler 创建调度器
func NewScheduler(maxWorkers int) *Scheduler {
	ctx, cancel := context.WithCancel(context.Background())
	return &Scheduler{
		maxWorkers:      maxWorkers,
		tasks:           make(map[string]*Task),
		taskResults:     make(map[string]*TaskResult),
		taskQueue:       make(chan *Task, 100),
		taskResultQueue: make(chan *TaskResult, 100),
		ctx:             ctx,
		cancel:          cancel,
		completedTasks:  make(map[string]bool),
	}
}

// AddTask 添加任务
func (s *Scheduler) AddTask(task *Task) error {
	s.mu.Lock()
	defer s.mu.Unlock()

	if task.ID == "" {
		task.ID = fmt.Sprintf("task-%d", len(s.tasks)+1)
	}
	if task.Name == "" {
		task.Name = task.ID
	}
	if task.Timeout == 0 {
		task.Timeout = 5 * time.Minute
	}
	if task.MaxOutput == 0 {
		task.MaxOutput = 5000
	}
	s.tasks[task.ID] = task
	return nil
}

// checkDependencies 检查任务依赖
func (s *Scheduler) checkDependencies() error {
	// 根据 Dependencies 去检查需要的任务是否存在在队列中
	for _, task := range s.tasks {
		for _, depID := range task.Dependencies {
			if _, exists := s.tasks[depID]; !exists {
				return fmt.Errorf("任务 %s 依赖的任务 %s 不存在", task.ID, depID)
			}
		}
	}
	return nil
}

// taskDispatcher 任务分发器
func (s *Scheduler) taskDispatcher() {
	// 检查依赖
	if err := s.checkDependencies(); err != nil {
		log.Printf("检查依赖失败, %v", err)
		return
	}
	// 没有依赖的任务加入队列
	// 有依赖的任务会在没有依赖的任务完成后执行
	s.mu.Lock()
	for _, task := range s.tasks {
		if len(task.Dependencies) == 0 {
			s.taskQueue <- task
		}
	}
	s.mu.Unlock()
}

// copyAndLog 复制并输出记录
func (s *Scheduler) copyAndLog(dst io.Writer, src io.Reader, prefix, taskName string) {
	scanner := bufio.NewScanner(src)
	for scanner.Scan() {
		line := scanner.Text()
		io.WriteString(dst, line+"\n")
		// 实时日志
		log.Printf("[%s] %s: %s", taskName, prefix, line)
	}
}

// runCommand 执行shell命令
func (s *Scheduler) runCommand(task *Task, output io.Writer) (int, error) {
	ctx, cancel := context.WithTimeout(s.ctx, task.Timeout)
	defer cancel()

	// 创建命令
	var cmd *exec.Cmd
	if len(task.Args) > 0 {
		cmd = exec.CommandContext(ctx, task.Cmd, task.Args...)
	} else {
		cmd = exec.CommandContext(ctx, "sh", "-c", task.Cmd)
	}

	// 设置工作目录
	if task.WorkDir != "" {
		cmd.Dir = task.WorkDir
	}

	// 设置环境变量
	if len(task.Env) > 0 {
		cmd.Env = append(os.Environ(), cmd.Env...)
	}

	// 设置输出
	stdoutPipe, err := cmd.StdoutPipe()
	if err != nil {
		return -1, err
	}
	stderrPipe, err := cmd.StderrPipe()
	if err != nil {
		return -1, err
	}

	// 启动命令
	if err := cmd.Start(); err != nil {
		return -1, err
	}

	// 并发读取 stdout 和 stderr
	var wg sync.WaitGroup
	wg.Add(2)
	go func() {
		defer wg.Done()
		s.copyAndLog(output, stdoutPipe, "STDOUT", task.Name)
	}()
	go func() {
		defer wg.Done()
		s.copyAndLog(output, stderrPipe, "STDERR", task.Name)
	}()
	wg.Wait()

	// 等待命令完成
	err = cmd.Wait()
	exitCode := cmd.ProcessState.ExitCode()
	if ctx.Err() == context.DeadlineExceeded {
		return exitCode, fmt.Errorf("任务执行超时(限时: %v)", task.Timeout)
	}
	return exitCode, err
}

// trimOutput 限制输出大小
func (s *Scheduler) trimOutput(output string, maxLines int) string {
	lines := bytes.Split([]byte(output), []byte("\n"))
	if len(lines) <= maxLines {
		return output
	}

	// 保留开头和结尾
	keep := maxLines / 2
	firstPart := lines[:keep]
	lastPart := lines[len(lines)-keep:]

	var result []byte
	result = append(result, bytes.Join(firstPart, []byte("\n"))...)
	result = append(result, []byte("\n... (忽略中间内容) ...\n")...)
	result = append(result, bytes.Join(lastPart, []byte("\n"))...)

	return string(result)
}

// executeTask 执行单个任务
func (s *Scheduler) executeTask(workerID int, task *Task) *TaskResult {
	result := &TaskResult{
		TaskID:     task.ID,
		TaskName:   task.Name,
		Status:     StatusRunning,
		StartTime:  time.Now(),
		RetryCount: 0,
	}

	log.Printf("Worker-%d 开始执行%s: %s", workerID, task.Name, task.Cmd)

	// 执行命令
	var output bytes.Buffer
	var err error
	var exitCode int

	for attempt := 0; attempt <= task.RetryCount; attempt++ {
		if attempt > 0 {
			log.Printf("任务 %s 第 %d 次重试...", task.Name, attempt)
			time.Sleep(task.RetryDelay)
		}

		result.RetryCount = attempt
		output.Reset()
		exitCode, err = s.runCommand(task, &output)

		if err == nil {
			result.Status = StatusSuccess
			break
		}

		if attempt == task.RetryCount {
			result.Status = StatusFailed
		}
	}

	result.EndTime = time.Now()
	result.Duration = result.EndTime.Sub(result.StartTime)
	result.ExitCode = exitCode
	result.Output = s.trimOutput(output.String(), task.MaxOutput)
	result.Error = err

	return result
}

// worker 工作协程
func (s *Scheduler) worker(id int) {
	defer s.wg.Done()
	for {
		select {
		case <-s.ctx.Done():
			return
		case task := <-s.taskQueue:
			result := s.executeTask(id, task)
			s.taskResultQueue <- result
		}
	}
}

// printResult 打印任务结果
func (s *Scheduler) printResult(result *TaskResult) {
	var statusColor *color.Color

	switch result.Status {
	case StatusSuccess:
		statusColor = color.New(color.FgGreen, color.Bold)
	case StatusFailed:
		statusColor = color.New(color.FgRed, color.Bold)
	case StatusCancelled:
		statusColor = color.New(color.FgYellow, color.Bold)
	default:
		statusColor = color.New(color.FgWhite)
	}

	statusColor.Printf("\n任务完成: %s (%s)\n", result.TaskName, result.TaskID)
	fmt.Printf("  状态: %s", result.Status)
	fmt.Printf("  耗时: %v", result.Duration)
	fmt.Printf("  开始: %s", result.StartTime.Format(time.DateTime))
	fmt.Printf("  结束: %s", result.EndTime.Format(time.DateTime))
	fmt.Printf("  退出码: %d", result.ExitCode)
	fmt.Printf("  重试次数: %d", result.RetryCount)

	if result.Error != nil {
		fmt.Printf("  错误: %v\n", result.Error)
	}

	if result.Output != "" {
		fmt.Println("  输出预览:")
		lines := bytes.SplitN([]byte(result.Output), []byte("\n"), 6)
		for i, line := range lines {
			if i >= 5 {
				fmt.Println("    ...(更多输出请查看完整日志)...")
			}
			if len(line) > 0 {
				fmt.Printf("    %s\n", line)
			}
		}
	}
	fmt.Println()
}

// checkDependentTasks 检查依赖任务
func (s *Scheduler) checkDependentTasks() {
	s.mu.Lock()
	defer s.mu.Unlock()

	for _, task := range s.tasks {
		// 如果任务已经在队列或已完成则跳过
		if s.completedTasks[task.ID] {
			continue
		}
		// 未进行任务依赖项是否全部满足
		allDepsCompleted := true
		for _, depID := range task.Dependencies {
			if !s.completedTasks[depID] {
				allDepsCompleted = false
				break
			}
		}
		// 如果依赖项项目全部满足，加入队列
		if allDepsCompleted && len(task.Dependencies) > 0 {
			// 标记已调度
			if !s.completedTasks[task.ID] {
				select {
				case s.taskQueue <- task:
					s.completedTasks[task.ID] = true
				default:
					log.Printf("队列任务已满, 任务 %s 等待调度", task.Name)
				}
			}
		}
	}
}

// resultProcessor 处理任务结果
func (s *Scheduler) resultProcessor() {
	for result := range s.taskResultQueue {
		s.mu.Lock()
		s.taskResults[result.TaskID] = result
		s.completedTasks[result.TaskID] = true
		s.mu.Unlock()
		// 打印结果
		s.printResult(result)
		// 检查是否有依赖此任务的任务可以执行
		s.checkDependentTasks()
	}
}

// AddTasks 批量添加任务
func (s *Scheduler) AddTasks(tasks ...*Task) {
	for _, task := range tasks {
		s.AddTask(task)
	}
}

// Start 启动调度器
func (s *Scheduler) Start() error {
	s.mu.Lock()
	if s.isRunning {
		s.mu.Unlock()
		return fmt.Errorf("程序已经在运行")
	}
	s.isRunning = true
	s.mu.Unlock()

	// 启动work
	for i := 0; i < s.maxWorkers; i++ {
		s.wg.Add(1)
		go s.worker(i)
	}

	// 启动结果处理器
	go s.resultProcessor()

	// 启动任务调器
	go s.taskDispatcher()

	log.Printf("调度器启动，最大并发数: %d", s.maxWorkers)
	return nil
}

// Stop 停止调度器
func (s *Scheduler) Stop() {
	log.Println("停止调度器...")
	s.cancel()
	s.wg.Wait()
	close(s.taskQueue)
	close(s.taskResultQueue)
	s.isRunning = false
	log.Println("调度器已停止")
}

// GetResults 获取所有任务结果
func (s *Scheduler) GetResults() map[string]*TaskResult {
	s.mu.Lock()
	defer s.mu.Unlock()

	results := make(map[string]*TaskResult)
	for k, v := range s.taskResults {
		results[k] = v
	}
	return results
}

// PrintSummary 打印汇总报告
func (s *Scheduler) PrintSummary() {
	results := s.GetResults()

	fmt.Println("\n" + strings.Repeat("-", 60))
	fmt.Println("任务执行汇总报告")
	fmt.Println(strings.Repeat("-", 60))

	var totalTime time.Duration
	successCount := 0
	failedCount := 0

	for _, result := range results {
		totalTime += result.Duration
		if result.Status == StatusSuccess {
			successCount++
		} else {
			failedCount++
		}
	}

	fmt.Printf("任务总数: %d\n", len(results))
	fmt.Printf("成功: %d\n", successCount)
	fmt.Printf("失败: %d\n", failedCount)
	fmt.Printf("总耗时: %v\n", totalTime)
	fmt.Printf("平均耗时: %v\n", totalTime/time.Duration(len(results)))

	// 打印详细结果表格
	fmt.Println("\n详细结果:")
	fmt.Println(strings.Repeat("-", 100))
	fmt.Printf("%-20s %-15s %-12s %-10s %-30s\n", "任务名称", "状态", "耗时", "退出码", "开始时间")
	fmt.Println(strings.Repeat("-", 100))
	for _, result := range results {
		statusStr := result.Status.String()
		if result.Status == StatusSuccess {
			statusStr = color.GreenString(statusStr)
		} else {
			statusStr = color.RedString(statusStr)
		}

		fmt.Printf("%-20s %-15s %-12v %-10d %-30s\n", result.TaskName, statusStr, result.Duration.Round(time.Millisecond), result.ExitCode, result.StartTime.Format(time.DateTime))
		fmt.Println(strings.Repeat("-", 100))
	}
}

func main() {
	// 创建调度器
	scheduler := NewScheduler(3)

	// 定义任务
	tasks := []*Task{
		{
			ID:         "Test A",
			Name:       "测试脚本A",
			Cmd:        "sh ./shell/test.sh 5 测试脚本A",
			Timeout:    10 * time.Minute,
			RetryDelay: 3 * time.Second,
			RetryCount: 2,
		},
		{
			ID:         "Test B",
			Name:       "测试脚本B",
			Cmd:        "sh ./shell/test.sh 3 测试脚本B",
			Timeout:    10 * time.Minute,
			RetryDelay: 3 * time.Second,
			RetryCount: 2,
		},
		{
			ID:         "Test C",
			Name:       "测试脚本C",
			Cmd:        "sh ./shell/test.sh 2",
			Timeout:    10 * time.Minute,
			RetryDelay: 3 * time.Second,
			RetryCount: 2,
		},
		{
			ID:           "Test D",
			Name:         "测试脚本D",
			Cmd:          "sh ./shell/test.sh 1 测试脚本D",
			Timeout:      10 * time.Minute,
			Dependencies: []string{"Test A", "Test B"},
			RetryDelay:   3 * time.Second,
			RetryCount:   2,
		},
	}

	// 添加任务
	scheduler.AddTasks(tasks...)

	// 启动调度
	if err := scheduler.Start(); err != nil {
		log.Fatal("启动失败:", err)
	}

	// 等待所有任务完成
	fmt.Println("调度器运行中, Ctrl+C 停止")

	// 监听中断信号
	sigChan := make(chan os.Signal, 1)
	signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)

	// 等待完成或者收到中断信号
	ticker := time.NewTicker(time.Second)
	defer ticker.Stop()

	for {
		select {
		case <-sigChan:
			fmt.Println("\n接收到中断信号，正在停止...")
			scheduler.Stop()
			scheduler.PrintSummary()
			return
		case <-ticker.C:
			// 检查是否所有任务都已完成
			results := scheduler.GetResults()
			if len(results) == len(tasks) {
				scheduler.Stop()
				scheduler.PrintSummary()
				return
			}
		}
	}
}

77. Worker Pool 的设计与实现

当前问题存在示例代码，可以前往GitHub查看

一开始接触 Go 并发的时候，很容易写出这样的代码：来一个任务，就起一个 goroutine。

go doWork(job)

这种写法在“任务不多、生命周期很短”的时候非常顺滑，也很符合直觉。

但当我把这个模式往真实场景里套时，很快就会意识到一个问题：goroutine 虽然便宜，但不是无限的。

当任务数量不受控、或者外部输入突增时，“来一个起一个”本质上是在把并发压力直接暴露给运行时。

这时候我才意识到，worker pool 并不是为了“提高并发”，而是为了限制并发。

从设计意图上看，worker pool 做的事情其实很简单：把「任务的产生」和「任务的执行」拆开。

任务可以源源不断地产生，但真正执行任务的 goroutine 数量是固定的。

在 Go 里，这个拆分几乎天然就会落到 channel 上。

type Job struct {
	ID int
}

func worker(id int, jobs <-chan Job) {
	for job := range jobs {
		fmt.Printf("[worker %d] 开始处理任务 %d\n", id, job.ID)
	}
}

这里的 worker 非常“老实”：

不创建 goroutine
不关心任务从哪里来
只做一件事：从 channel 里拿任务，处理，然后继续等下一个

这和 PHP 世界里常见的“一个请求进来 → 一条执行路径跑到底”是完全不同的感觉。

这里更像是：程序结构先被稳定下来，数据在结构里流动。

接下来是 pool 本身，也就是“开多少个 worker”。

func startWorkerPool(workerNum int, jobs <-chan Job) {
	for i := 0; i < workerNum; i++ {
		go worker(i, jobs)
	}
}

这个地方让我第一次意识到 Go 并发的一个特点：goroutine 的创建是集中发生的，而不是分散在业务逻辑里。

worker 的数量在这里就已经定死了，后面的代码即使疯狂往 jobs 里塞任务，也只会有这几个 goroutine 在干活。

任务的产生端反而变得非常“普通”。

func main() {
	jobs := make(chan Job)

	startWorkerPool(3, jobs)

	for i := 0; i < 10; i++ {
		jobs <- Job{ID: i}
	}

	close(jobs)
}

如果你站在 PHP 的视角看这段代码，会发现一个很有意思的变化：主 goroutine 不负责干活，它只是把任务“投递”出去。

这里没有锁，没有共享状态，甚至没有显式的并发控制语句。

并发被“压缩”进了 channel 的语义里。

在我理解 worker pool 的过程中，一个比较重要的转折点是：我开始把它当成一种结构设计，而不是并发技巧。

worker pool 本身并不聪明：

不保证任务顺序
不保证任务成功
不关心任务失败如何处理

它唯一保证的是：同一时间，最多只有 N 个任务在被执行。

这让我意识到一个事实：worker pool 管的是“并发度”，不是“业务逻辑” 。

当你开始往真实系统靠的时候，worker pool 往往会自然地多长出一些东西。

比如，增加退出控制：

func worker(ctx context.Context, id int, jobs <-chan Job) {
	for {
		select {
		case <-ctx.Done():
			return
		case job, ok := <-jobs:
			if !ok {
				return
			}
			fmt.Printf("worker %d handling job %d\n", id, job.ID)
		}
	}
}

这时候你会发现，worker pool 和「优雅关闭」「服务生命周期」已经开始产生联系了。

它不再只是一个并发工具，而是服务结构的一部分。

回头看，worker pool 对我来说最大的价值，不是“学会了一种并发模式”，而是让我开始接受这样一种思路：不要让并发随意生长，先设计结构，再让任务流经结构

这可能也是 Go 和 PHP 在并发模型上给我最大的心理差异。

PHP 更像是“请求驱动代码执行”，而 Go 更像是“结构驱动任务流动”。

worker pool，只是这个思路里一个非常早、也非常典型的例子。

78. 限流、超时与失败控制

刚开始从 PHP 转到 Go，看「限流、超时、失败控制」这些词，会下意识把它们当成“框架能力”或者“中间件功能”。

在 PHP 世界里，很多时候确实是这样：Nginx、FPM、框架、网关已经帮你做掉了，你只是在配置层面“启用”。

但在 Go 里，我慢慢意识到，这三件事更像是代码层面的时间与容量意识，而不是某个现成的功能开关。

限流，本质上是在承认一件事：系统不是无限的。

不是“防止被打爆”，而是你需要明确告诉自己：我现在愿意同时处理多少件事。

在 Go 里，这种意识很自然地会落到 channel 上。

var limiter = make(chan struct{}, 10) // 同时最多处理 10 个请求

func handle(req int) {
    limiter <- struct{}{}        // 进入限流区
    defer func() { <-limiter }() // 处理完成后释放

    // 模拟业务处理
    time.Sleep(200 * time.Millisecond)
    fmt.Println("handled", req)
}

这个写法一开始看着有点“原始”，但用久了会发现它非常直观：channel 的容量就是你对系统承载能力的一个明确表态。

和 PHP 不同的是，这里不是等队列无限堆积，而是你在代码里清楚地画了一条线：“超过这个数量，我宁可等，也不继续往里塞”。

接着是超时。

超时在 Go 里不是一个“异常情况”，而是一种默认应该存在的边界。

这点和 PHP 的感受差异很大。PHP 更多是：“这个请求慢了，那就慢了，反正进程也快结束了。”

而 Go 常驻进程的视角是：“如果我不主动设定时间，慢就会变成常态。”

ctx, cancel := context.WithTimeout(context.Background(), 300*time.Millisecond)
defer cancel()

err := doSomething(ctx)
if err != nil {
    fmt.Println("failed:", err)
}

一开始我会纠结：“这个 300ms 是不是太武断了？”

后来想通了，它并不是一个精确的承诺，而是一个态度：超过这个时间，我不再认为这件事值得继续消耗资源。

而 context 的设计让这件事不是“强行中断”，而是层层传递的放弃信号。

谁最先意识到“不值得继续”，谁就停下来。

失败控制是这三者里最容易被误解的。

很多时候我们会把失败当成“异常路径”，但在 Go 的世界里，失败反而更像是一种常规结果。

if err != nil {
    return err
}

写多了会发现，这不是消极，而是非常诚实。

Go 不鼓励你“兜底一切”，而是逼你在每一层都想清楚：

这一步失败了，还要不要继续？
是立即返回，还是重试？
重试几次算合理？

for i := 0; i < 3; i++ {
    err := doSomething()
    if err == nil {
        return nil
    }
    time.Sleep(100 * time.Millisecond)
}
return errors.New("retry failed")

这里没有什么“高级策略”，但它让失败变成了一个被认真对待的路径，而不是日志里的一行抱怨。

把这三件事放在一起看，我慢慢发现它们其实在解决同一件事：如何在不确定的世界里，给系统设定清晰的边界。

限流：我一次只接这么多
超时：我只等这么久
失败控制：我只尝试到这个程度

它们并不会让系统“更强”，但会让系统更可控。

而这恰恰是从 PHP 过来后，我对 Go 最明显的一次理解变化：不是“能不能跑”，而是“什么时候该停”。

79. 从“能跑”到“稳定”的改造过程

一开始的“能跑”，通常就是一个最朴素的 HTTP 服务。

它没有任何边界意识，但逻辑是完整闭合的。

package main

import (
	"fmt"
	"net/http"
	"time"
)

func main() {
	http.HandleFunc("/work", func(w http.ResponseWriter, r *http.Request) {
		// 模拟一个耗时操作
		time.Sleep(800 * time.Millisecond)
		fmt.Fprintln(w, "ok")
	})

	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

这个程序非常“干净”：请求来了就做事，做完就返回。

慢，也只是慢而已。

问题在于：你不知道慢到什么时候算不合理。

于是第一次改造，往往是给请求加上时间边界。

这一步并不是为了优化性能，而是为了让“放弃”变得可描述。

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"
)

func main() {
	http.HandleFunc("/work", func(w http.ResponseWriter, r *http.Request) {
		ctx, cancel := context.WithTimeout(r.Context(), 500*time.Millisecond)
		defer cancel()

		err := doWork(ctx)
		if err != nil {
			http.Error(w, err.Error(), http.StatusGatewayTimeout)
			return
		}

		fmt.Fprintln(w, "ok")
	})

	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func doWork(ctx context.Context) error {
	select {
	case <-time.After(800 * time.Millisecond):
		return nil
	case <-ctx.Done():
		return ctx.Err()
	}
}

现在这个服务仍然“能跑”，但已经多了一层态度：超过 500ms，这件事就不再值得继续。

接下来，当并发请求上来时，你会发现另一个问题：就算每个请求都有超时，同时跑太多也会把自己拖死。

这时候改造点通常落在并发数量上。

package main

import (
	"context"
	"fmt"
	"net/http"
	"time"
)

var limiter = make(chan struct{}, 5) // 同时最多 5 个请求在处理

func main() {
	http.HandleFunc("/work", func(w http.ResponseWriter, r *http.Request) {
		select {
		case limiter <- struct{}{}:
			defer func() { <-limiter }()
		default:
			http.Error(w, "too many requests", http.StatusTooManyRequests)
			return
		}

		ctx, cancel := context.WithTimeout(r.Context(), 500*time.Millisecond)
		defer cancel()

		err := doWork(ctx)
		if err != nil {
			http.Error(w, err.Error(), http.StatusGatewayTimeout)
			return
		}

		fmt.Fprintln(w, "ok")
	})

	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func doWork(ctx context.Context) error {
	select {
	case <-time.After(800 * time.Millisecond):
		return nil
	case <-ctx.Done():
		return ctx.Err()
	}
}

这里有一个非常典型的“稳定性取舍”：当系统已经忙不过来了，直接拒绝新请求，而不是让所有请求一起慢。

这在“能跑”的阶段通常很难下这个决定，但在“稳定”的视角里，这是在保护已经进来的请求。

最后一个常见变化，是你不再指望“一次就成功”。

失败不再只是返回错误，而是变成一个可控的过程。

package main

import (
	"context"
	"errors"
	"fmt"
	"net/http"
	"time"
)

var limiter = make(chan struct{}, 5)

func main() {
	http.HandleFunc("/work", func(w http.ResponseWriter, r *http.Request) {
		select {
		case limiter <- struct{}{}:
			defer func() { <-limiter }()
		default:
			http.Error(w, "too many requests", http.StatusTooManyRequests)
			return
		}

		ctx, cancel := context.WithTimeout(r.Context(), 1*time.Second)
		defer cancel()

		err := retry(ctx, 3, func() error {
			return doWork(ctx)
		})
		if err != nil {
			http.Error(w, err.Error(), http.StatusBadGateway)
			return
		}

		fmt.Fprintln(w, "ok")
	})

	fmt.Println("server start at :8080")
	http.ListenAndServe(":8080", nil)
}

func doWork(ctx context.Context) error {
	select {
	case <-time.After(400 * time.Millisecond):
		// 模拟偶发失败
		return errors.New("random failure")
	case <-ctx.Done():
		return ctx.Err()
	}
}

func retry(ctx context.Context, times int, fn func() error) error {
	var err error
	for i := 0; i < times; i++ {
		if err = fn(); err == nil {
			return nil
		}
		select {
		case <-time.After(100 * time.Millisecond):
		case <-ctx.Done():
			return ctx.Err()
		}
	}
	return err
}

到这里，这个服务并没有“更聪明”，

但它已经具备了一种稳定时的自我克制：

不无限接请求
不无限等待
不无限重试

回头看，“能跑”到“稳定”的改造过程，并不是一步到位的架构升级，而是一点点把隐含假设变成显式边界的过程。

十八、性能与运行时感知

80. Go GC 的基本行为

刚接触 Go 的时候，我对 GC 的感知几乎是“它存在，但我不用管”。

这种感觉和写 PHP 时其实很像：脚本结束，内存自然就回收了，至于中间发生了什么，并不会成为心智负担。

直到我开始写常驻进程，这种“无感”才第一次被打破。

package main

func main() {
	for {
		data := make([]byte, 1024*1024)
		_ = data
	}
}

这段代码什么都不做，只是不断分配 1MB 的内存。

它能跑，而且跑得“看起来没问题”，CPU 不高，程序也没崩。

但这里其实已经触发了 Go GC 的一个最基本行为：GC 并不是在内存“用完”时才发生，而是在分配过程中被持续触发的。

在 Go 里，内存分配本身就是 GC 的信号源之一。

进一步观察时，我开始意识到一个和直觉不太一样的点：GC 并不是“停下来一次性清干净”。

package main

import (
	"fmt"
	"time"
)

func main() {
	go func() {
		for {
			_ = make([]byte, 1024*1024)
			time.Sleep(10 * time.Millisecond)
		}
	}()

	for {
		fmt.Println("running")
		time.Sleep(100 * time.Millisecond)
	}
}

程序一边分配内存，一边持续输出日志。

如果 GC 是那种“全停”的行为，那么理论上我应该能看到明显的卡顿。

但实际感受是：输出节奏基本稳定，没有那种“突然停一下”的感觉。

这是我第一次真正意识到：Go 的 GC 设计目标，从一开始就不是“回收得最快”，而是“别太打扰程序运行”。

它是并发的、增量的，而不是一个集中爆发的清扫动作。

不过，“不太打扰”并不等于“完全没有代价”。

package main

func alloc() []byte {
	return make([]byte, 1024)
}

func main() {
	for i := 0; i < 1_000_000; i++ {
		_ = alloc()
	}
}

这类代码在功能上毫无问题，但它揭示了 GC 的另一个基本事实：GC 的成本，和“活跃对象的数量”强相关。

不是分配得多就一定慢，而是分配之后还活着的对象越多，GC 越辛苦。

这也解释了一个常见但容易被误解的现象：

有些程序分配频繁，但 GC 压力不大
有些程序分配并不多，但一到 GC 就抖一下

问题往往不在“分配了多少”，而在“留住了多少”。

从 PHP 的视角来看，这一点非常不直观。

在 PHP 里，请求结束就是天然的“内存清零点”；

而在 Go 里，程序没有“请求结束”这个时间点，只有对象是否仍然可达。

type Cache struct {
	data []byte
}

func main() {
	c := &Cache{
		data: make([]byte, 1024*1024*100),
	}
	_ = c
	select {}
}

这里没有循环，也没有持续分配。

但这 100MB 内存会一直被认为是“活的”。

GC 并不会因为“它好久没被用过”而回收它，

只要引用关系还在，它就仍然属于运行时的一部分。

所以在我理解里，Go GC 的“基本行为”其实可以浓缩成几句话：

GC 是持续发生的背景活动，不是阶段性的大扫除
它更在意程序的平稳运行，而不是极限吞吐
回收压力的核心，不是分配频率，而是存活对象规模
在常驻服务中，对象的生命周期设计本身，就是性能设计的一部分

也正是从这里开始，我才意识到：性能问题并不是“写慢代码”，而是在不知不觉中，和运行时站到了对立面。

81. 什么时候需要关注内存分配

一开始写 Go 的时候，我几乎不会主动去想“这行代码分配了多少内存”。

func handle() {
	data := make([]int, 0)
	for i := 0; i < 1000; i++ {
		data = append(data, i)
	}
}

这段代码非常自然，也完全没问题。

如果这是一个偶尔调用的函数，或者只是启动时跑一次，那它的内存分配几乎可以忽略。

所以我慢慢意识到一个前提：只有在“被频繁执行”的路径上，内存分配才开始有意义。

不是所有代码都值得被当成性能代码来看。

真正让我开始关注分配的，往往是这种场景：

func handler(w http.ResponseWriter, r *http.Request) {
	buf := make([]byte, 4096)
	_, _ = r.Body.Read(buf)
}

单次看，这点内存微不足道。

但当它变成一个 QPS 很高的 HTTP 接口时，事情就变了。

这里并不是说 “4096 字节很大”，而是这个分配，会在每一次请求中发生。

当我把注意力从“这次分配多不多”转移到“这行代码会被跑多少次”时，视角就完全变了。

还有一种情况，是代码结构让我开始警觉的。

func buildResult(items []Item) []Result {
	var results []Result
	for _, item := range items {
		results = append(results, Result{
			ID:   item.ID,
			Name: item.Name,
		})
	}
	return results
}

它逻辑清晰、可读性也不错。

但如果这个函数处在一个嵌套循环里，或者是链路中的中间层，

那么这里的 slice 扩容、对象构造，就会被放大很多倍。

这时我开始学会问自己一个问题：这个分配，是不是“每一层都在默默做一遍”？

当分配隐藏在“看起来很干净的抽象”里时，它往往最容易被忽略。

和 PHP 对比时，这种感觉尤其明显。

在 PHP 里，很多临时变量本来就是“请求级”的；

它们会在请求结束时被统一释放，开发者很少去想生命周期。

但在 Go 里，请求只是业务概念，不是内存边界。

type Service struct {
	tmp []byte
}

func (s *Service) Handle() {
	s.tmp = make([]byte, 1024)
}

这段代码在功能上没问题，但它让一次“本该是临时的分配”，变成了一个长期存活的对象。

这类情况往往不会在功能测试里暴露，而是在服务跑了一段时间后，才慢慢体现在内存占用和 GC 行为上。

还有一个我后来才意识到的信号：当我开始觉得 GC “有点频繁”时，问题往往已经不是 GC 本身了。

for {
	data := make([]byte, 1024)
	process(data)
}

GC 频繁，通常只是结果。

真正的原因，往往是这类代码出现在了一个我没意识到的热点路径里。

也正因为如此，我逐渐形成了一个比较保守的判断标准：

冷路径上的分配，可以先忽略
启动阶段的分配，通常不重要
请求级、循环内、并发路径上的分配，值得多看一眼
一旦和 GC 行为产生“体感关联”，就该认真对待了

所以对我来说，“关注内存分配”并不是一件一开始就要做的事。

它更像是一个阶段性的意识变化：当程序开始长时间运行、并且有了稳定负载之后，内存分配就不再只是实现细节，而开始参与性能结果。

82. pprof 的基础使用

一开始产生“要不要做性能分析”的念头，其实非常模糊。

程序能跑，功能也对，只是偶尔会冒出一种不太确定的感觉：我不知道它现在跑得算不算健康。

不是慢到出问题的那种，而是如果哪天负载上来，我完全没有判断依据。

在这种状态下，“性能分析”这个词本身就显得很抽象。

我并不是要做极致优化，而只是想回答一些很基础的问题：

CPU 时间大概花在了哪里
内存是不是在持续增长
GC 是否在我没注意到的时候频繁发生

直到这时，我才第一次意识到：这些问题，靠读代码是回答不了的。

pprof 就是在这个背景下进入视野的。

它并不是一个额外安装的工具，而是 Go 运行时自带的一套 profiling 能力。

import _ "net/http/pprof"

第一次看到这行代码的时候，我的反应其实有点意外：

原来只需要一个空导入，就可以把整个运行时暴露出来。

这也让我对 pprof 的定位变得清晰起来：它不是调试器，也不是监控系统，而是运行时的“侧写”。

要使用 pprof，最基础的一步其实很简单：给程序留一个可以被观察的入口。

package main

import (
	"log"
	"net/http"
	_ "net/http/pprof"
)

func main() {
	go func() {
		log.Println(http.ListenAndServe(":6060", nil))
	}()

	select {}
}

这段代码并没有改变程序的业务逻辑，它只是额外开启了一个 HTTP 服务，用来暴露 profiling 数据。

当我第一次访问 /debug/pprof/ 时，才真正意识到：pprof 不是一次性的分析，而是一扇随时可以打开的窗口。

接下来，才轮到“怎么用”。

pprof 并不是在浏览器里点点看看的工具，真正的使用方式，还是通过命令行。

go tool pprof http://localhost:6060/debug/pprof/heap

这一刻，我并没有指望它给我答案。

我只是想知道：如果我真的要看内存，现在应该从哪里开始？

heap profile 给出的，正是这样一个起点：当前进程里，内存主要花在了哪些地方。

CPU profiling 的使用方式也类似，只是多了一个“时间窗口”。

go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

这里的 30 秒，并不是为了“抓住问题”，

而是为了让我建立一个概念：性能不是某一瞬间的状态，而是一段时间内的分布。

这和我之前那种“打日志、凭感觉判断快慢”的方式，完全不同。

慢慢地，我才意识到 pprof 的使用门槛其实并不高，真正的难点不在“怎么跑命令”，而在怎么看结果。

(pprof) top

这个命令非常朴素，却是我最常用的入口。

它不会试图解释因果，只是把消耗排好顺序。

而排序，本身就已经是一种过滤。

所以回过头看，我对 pprof 的理解经历了一个很清晰的变化过程：

一开始只是模糊地想“要不要做性能分析”
然后发现代码本身给不了我答案
接着了解到 Go 自带 pprof 这样的运行时工具
最后学会用它去确认，而不是猜测

pprof 并没有让我立刻写出更快的代码，但它让我第一次有了一种感觉：我不是在对着黑盒调性能，而是在观察一个正在运行的系统。

83. 常见性能误区（过度并发、过度抽象）

刚开始写 Go 的时候，我对并发几乎是天然信任的。

for _, item := range items {
	go process(item)
}

这段代码看起来就像是在“正确使用 Go”。

goroutine 很轻，语法也简单，不用就有点浪费。

但真正让我开始怀疑这种写法的，并不是性能问题，而是运行一段时间后的不确定性。

CPU 偶尔飙高，内存曲线变得难以解释，而我却很难用代码结构去回答一个问题：现在，到底有多少事情在同时发生？

过度并发的第一个误区，往往不是“太慢”，而是失去了对并发规模的感知。

func handle(items []Item) {
	for _, item := range items {
		go func(it Item) {
			process(it)
		}(item)
	}
}

这类代码在小数据量下表现得非常“健康”，但一旦输入规模变化，goroutine 的数量就会线性放大。

问题不在于 goroutine 本身，而在于：它们的创建，几乎没有成本感知。

当我开始用 pprof 或 runtime 指标观察程序时，才意识到很多性能问题，其实是并发失控的副作用。

另一个容易被忽略的点是：并发并不等于并行，更不等于更快。

for i := 0; i < 100; i++ {
	go work()
}

如果 work 本身是 I/O 阻塞的，这样做可能是对的；

但如果它主要是 CPU 计算，那我只是让调度器更忙而已。

这时性能问题往往表现为：

CPU 利用率很高
吞吐却没有明显提升
延迟反而变得不稳定

并发在这里，已经从“工具”变成了“噪音”。

相比并发，过度抽象的误区更隐蔽一些。

type Processor interface {
	Process([]byte) []byte
}

接口本身没有错，

问题在于它常常被放在调用频率极高的路径上。

当我把一段逻辑拆成很多“小而优雅”的组件时，代码看起来更清爽了，但运行时却多了层层间接调用、对象构造和逃逸风险。

这些开销单独看都很小，但在热点路径上，会被无限放大。

在 PHP 里，这种抽象成本往往被请求生命周期“抹平”；

而在 Go 里，它们会真实地体现在 CPU 和内存曲线上。

func handle(p Processor, data []byte) []byte {
	return p.Process(data)
}

当我在 pprof 里看到这些“看起来很干净的代码”

出现在 top 列表中时，才意识到一个事实：抽象并不是免费的，只是它的成本往往不在我写代码的时候出现。

后来我慢慢形成了一些很朴素的自我约束：

并发之前，先想清楚“规模”
抽象之前，确认它是否在热点路径
不要为了“Go 风格”，去强行并发或拆层
当性能成为问题时，优先怀疑结构，而不是语法

性能误区的可怕之处，不在于写错代码，而在于：它们通常来自“看起来很对的选择”。

所以在这个章节的结尾，我对“性能与运行时感知”的理解，其实变得很简单：

不是学会了多少优化技巧，而是开始意识到：每一个看似优雅的设计决定，都会在运行时留下痕迹。

当我愿意去看这些痕迹、理解它们，性能就不再是一件靠运气的事情了。

2025 年度复盘：一些工作之外的项目、工具和想法

Thu, 01 Jan 2026 04:26:24 GMT

2025 年对我来说，是一个节奏明显不一样的年份。

工作本身发生了一些变化，一方面是内容上的调整，另一方面也因为单位的特殊性，涉及比较高的保密要求，很多事情并不适合写出来。再加上整体节奏不像去年那样紧绷，我不再每天十几个小时泡在公司里，于是突然多出了一部分可以自由支配的时间。

这些时间我几乎没有拿去“休息”，而是顺手用来做了一些事情。它们大多发生在工作之外，也基本不和工作直接相关。

之所以会这么做，其实和我的一些想法有关。

我并不是什么大厂背景的技术人，也没有年薪几十、上百万的预期。对我来说，世界并不只是由头部互联网公司组成的，更多的是数量庞大的普通公司、民营企业，而它们中的大多数，甚至还没真正走到“追逐前沿技术”的阶段。很多时候，连负载均衡这种事情，都是相当遥远的。

也正因为如此，我对所谓的年龄焦虑、技术斩杀线之类的说法，并没有太强的感受。

在我看来，去掉互联网的泡沫之后，只要我能够持续创造出有价值的东西，就一定能拿到与之相匹配的回报。只不过在泡沫之中，这种“匹配价值的回报”，往往会显得不那么诱人，甚至远低于某些人的心理预期。

但时代的浪潮并不是靠个人意志就能左右的。正是因为太多人执着于攀登那些遥不可及的浪尖，才会在浪潮退去的时候，来不及反应，被拍得措手不及。

这当然只是我个人的理解，并不是什么结论，也谈不上评判。只是基于这样的想法，比起焦虑那些还没真正落地的技术，或者遥遥无期的方案，我更愿意把时间花在一件事上：尽量稳固自己的基本盘

至少让我自己，始终是一个在未来还能持续创造价值的人。

这篇文章想记录的，就是在这样的心态下，这一年里，我在这些空出来的时间里，都折腾了些什么。

一月-从一个自用项目开始的祛魅

2025 年的开头，我把之前写的积分商城和弹幕机器人整理了一下，正式开源，并补上了 Docker 部署方案。

这算是我比较完整地、从实战角度重新审视 Docker 的一次机会。结论其实挺简单的：

如果真的涉及多实例、复杂部署、负载均衡，那 Docker 确实很好用；但如果只是一个一台服务器就能跑得很舒服的小项目，它也没有被说得那么“神”。

对我来说，这更像是一次技术祛魅。不是说 Docker 不重要，而是它并不需要出现在每一个项目里。

这个月还顺手给机器人补了禁言一类的基础能力，整体还是“我自己用得顺就行”的阶段。

二月-开始意识到有人在用

二月做的事情不算多，但对我来说很重要。

我开始收到一些使用者的反馈，于是给积分商城和弹幕机器人补了两个看起来很小的功能：

兑换成功后的邮件通知
虚拟商品支持只填写邮箱，不再强制填地址

这些功能本身没什么技术含量，但它们让我第一次清楚地意识到一件事：
这个东西，已经不是只给我自己用的了。

从这个时候开始，我对这个项目的态度发生了一点变化。

三月-开始有意识地把东西封装出来

三月是一个很明显的转折点。

一方面，我帮朋友做了一个记录奶茶消费的小程序。虽然这个事情最后并没有继续推进，但让我完整地重温了一次微信小程序的开发流程，也顺手写了一篇博客记录。

另一方面，我开始认真思考一件以前其实没怎么想过的事：

工作中反复遇到的这些东西，能不能少写几遍？

于是这个月我做了不少偏“基础建设”的事情：

整理了一套 webman + vue3 + naiveui 的后台脚手架
用 Go 写了一个很简单的错误日志收集小站，顺便熟悉 Go
把公司里一直在用的 MySQL 备份脚本整理完善后开源
给积分商城和弹幕机器人加了签到系统

从这个阶段开始，我做项目时的关注点慢慢从
功能写没写完 变成了 下次还要不要再写一遍

四月-封装开始变成一件很自然的事

四月基本可以算是一个「封装月」。

我把之前在项目里零零碎碎用到的一些功能，开始系统性地拆出来，变成独立的包：

手机号归属地查询、身份证归属地查询、地址解析、URL 签名、TOTP 校验、规则引擎，还有一堆 utils 级别的小工具。

它们大多不复杂，也谈不上什么设计模式，但都有一个共同点：
我真的在项目里反复用到它们。

同一时间，积分商城和弹幕机器人也加上了 PK 播报能力，开始慢慢往「更像一个完整系统」的方向走。

五月-从我在用到我要维护

五月我开始认真对待 GitHub 上的这些仓库。

我给不少项目补了双语 README，重构了积分商城和弹幕机器人的管理后台，也终于给商城首页加上了分页这个功能，还有一些校验之类的。

其实一开始就该有，只是当初完全没想到真的会有这么多人用。

也是在这个阶段，我第一次明确意识到：这个项目不能再按“自用工具”的标准来对待了。

这个月我还沉迷了一阵子 AI，给自己搞了一套每日热点新闻推送，每天早上自动收集、处理，只留下我真正可能感兴趣的内容。纯粹是为了让自己少刷一点无意义的信息流。

六到八月-系统开始变复杂

这几个月，积分商城和弹幕机器人的变化开始变得比较明显：

拆分货币体系（因为根据需求加入了签到系统，而签到系统得到的奖励代币又要跟上舰的积分有所区别）
引入返利和双货币逻辑
完善了接口加密逻辑，分别封装成 npm 包和 PHP 包
给项目接口的加密方式都升级成了封装的 AES + RSA 混合加密

这些变化大多不是「我想加」，而是有人真的反馈过来了需要使用，以及有认真的在使用的过程中遇到了问题，于是不得不去想更合理的设计。

与此同时，我也继续把工作中那些「懒得一次次封装」的东西独立出来，比如 ip138接口封装、促销策略引擎、ID 生成器，还有一个让老板自己查数据库的小工具。

有些工具，说实话，做出来就是为了让我清净一点。

九到十月-换工具解决问题

这段时间我做的事情跨度有点大。

B 站小小的发力，更新了一轮风控，大部分接口都需要通过 WBI 签名鉴权了，不过好在问题不是很大，顺利解决了。

直播间数据流也迎来了一波更新，部分数据开始通过 protobuf 传输，protobuf 逆向确实让我头疼了两天，不过好在 B 站对这一部分貌似也是浅尝辄止，并没有大范围推广，因此解决这个问题并没有产生天大的工作量。

也首次尝试用 Wails 和 Go 做桌面应用。

还有一个天大的事情，九月份我发现了一个不是很健康的，带颜色的小说网站的漏洞。

色情果然是除战争外的第一生产力推动力量，火速用 python 搞了个简易爬虫，爬了人家八万多篇小短文，可惜人家在十二月中的时候改版了整个系统，在后端把爬虫堵死了。

虽然说感觉如果可以伪造IP，好好做一个爬虫的话应该还可以爬，但是他一个月都更新不了30篇，八万多篇已经不知道是他多少年的存货了，我也不想在这个事情上折腾太久，八万多篇都不知道看到猴年马月了。

然后因为想要更高效的筛选小说，比如我搜索一个情景或者剧情方向，就给我找到最符合方向的小说，因此用到了向量搜索，去研究了 Milvus，做了向量数据库的 REST 封装并且公开了。

当然只是公开了向量数据库相关的封装，并没有公开小说，公开那玩意违法，只能我自己享用了。

以前的我可能会在需要实现某种功能时投入更高的技术能力硬莽过去，而现在，在工作中慢慢失去了那股热情的我，在面对一些语言天生劣势的时候比起硬莽可能会更加倾向于去更换具备足够优势的语言。

感觉就好像年轻的时候坚信一力降十会，老了之后跟别人讲一巧破百拙

不过只要解决了问题就好，了解的东西增加了之后确实会慢慢摆脱那种既分高下也决生死的冲劲，我说不上这是不是好事，但目前想来也还不觉得是个坏事。

同一时间，在我使用了一段时间 Hexo 作为自己的博客框架后，也渐渐感到不太满意，最后决定把博客迁移到 Astro，并顺手把之前散落在各处的 demo 和小工具慢慢收拢回来。

十一到十二月-开始维护自己的空间

年底的节奏明显慢了下来，可能工作上的事情多了一点点，出差那些让我没有那么多闲心去折腾别的。

我把更多精力放在整理和维护上：继续打磨 Astro 博客，补文档，做提问箱，完善小工具页面；

给积分商城和弹幕机器人补齐文档；

把错误日志相关的工具重新整理了一下；

顺手写了一些真正能长期用的小工具。

这些事情本身并不刺激，但它们让我第一次产生了一种比较踏实的感觉：有些东西，我可能会一直维护下去。

写在最后

我一直不觉得自己是个会写文章的人。

对我来说，大多数博客的产生方式都很固定：先遇到一个问题，解决它，然后顺手记下来。

回头看这一年，做过的东西确实不少，但真正重要的，可能并不是具体写了多少代码、开了多少仓库，而是我越来越清楚自己想要什么样的节奏。

不是在浪尖上冲刺，也不是彻底躺平，而是尽量让自己始终处在一个还能持续产出、也能长期维持的状态里。

比起对某项技术的热情，或者研究了多少看起来很厉害的东西，我可能更在意的，是自己在未来的环境里，能不能持续创造出有价值的东西。

当然，也会有人觉得，进入所谓的 AI 时代之后，很多事情老板张张嘴、让 AI 做就行了，那这些东西自然也就不值钱了。

但实际情况往往没这么简单。

老板对着 AI 随便描述一句需求，和一个有经验的人带着明确的问题、约束和判断去用 AI，最终得到的结果，差别是非常大的。

工具在变，但解决问题的经验，以及看问题、拆问题、兜底问题的能力，并不会因此消失。它们也许会随着泡沫的起落而被低估，但很难真正变得一文不值。

就像过去的八级钳工一样。随着数控机床的精度不断提高，单纯去和机器比精度，确实已经没有太多意义了。但在非标场景下如何处理问题，设备出现异常时如何兜底，这些才是八级工真正有价值的地方。

对我来说，这一年做的很多事情，本质上也是在不断积累这些东西。

它们不一定时髦，也未必耀眼，但至少让我确信一件事：只要还能持续解决问题，我就还站在牌桌上

一次受限环境下的 MySQL 数据导出与“可交付化”实践

Fri, 26 Dec 2025 08:39:17 GMT

平时其实很少会专门写数据库导出的事情。

这种活本身并不复杂，零零散散也做过很多次，大多数时候也不会留下什么记录。

这一次之所以单独记下来，主要还是因为当时遇到了一些比较具体、也比较现实的限制条件：

我需要在比较短的时间里接手一个并不熟悉的 MySQL 实例，把里面的数据整理出来，而且这些数据最终并不是只给工程师看。

从一开始就意识到的一个问题

在动手之前，其实有一件事情我是比较明确的：

.sql 文件对工程师很友好，但对非技术人员几乎没有可用性。

对工程师来说：

.sql 是最可靠的备份形式
可以恢复、可以校验、可以长期保存

但换一个视角：

很多人甚至不知道怎么打开 .sql
就算打开了，也很难直接理解表结构
想筛选、查某一条记录，几乎是不可能的

也就是说，单纯把数据库备份下来，并不等于问题已经解决了。

后面迟早还是要把数据整理成一种“能被直接使用”的形式。

所以我当时心里其实是把这件事拆成了两步：

先保证数据完整地留下来
再考虑怎么把数据变成别人也能看懂的样子

先做一份完整的数据库备份

基于这个判断，我做的第一件事，还是先把整个 MySQL 实例完整备份下来。

这一步本身并不复杂，也谈不上什么技巧，只是对我来说，先有一份全量、可恢复的备份，会比较安心。后面无论怎么处理数据，至少不会有“回不去”的问题。

为了省事，我写了一个简单的 shell 脚本，用来：

自动获取所有业务数据库
排除系统库
逐个数据库执行 mysqldump
直接流式压缩成 .sql.gz

脚本本身也只是把平时常用的命令整理了一下：

#!/usr/bin/env bash

## gunzip < app.sql.gz | mysql -u root -p
## nohup ./dump_all_dbs.sh host port root 'password' > 备份日志.log 2>&1 &

set -e

HOST="$1"
PORT="$2"
USER="$3"
PASS="$4"

if [ $# -ne 4 ]; then
  echo "Usage: $0 <host> <port> <user> <password>"
  exit 1
fi

OUT_DIR="Mysql备份_$(date +%F_%H%M%S)"
mkdir -p "$OUT_DIR"

MYSQL="mysql -h${HOST} -P${PORT} -u${USER} -p${PASS} --batch --skip-column-names"
DUMP_BASE_OPTS="
  --single-transaction
  --routines
  --events
  --triggers
  --hex-blob
  --set-gtid-purged=OFF
  --default-character-set=utf8mb4
"

echo "==> 正在从获取数据库列表 ${HOST}:${PORT}"

DATABASES=$($MYSQL -e "
  SELECT schema_name
  FROM information_schema.schemata
  WHERE schema_name NOT IN
    ('mysql','information_schema','performance_schema','sys');
")

if [ -z "$DATABASES" ]; then
  echo "未找到数据库!"
  exit 0
fi

echo "==> 要转储的数据库:"
echo "$DATABASES"
echo

for DB in $DATABASES; do
  FILE="${OUT_DIR}/${DB}.sql.gz"
  echo "==> 转储数据库: ${DB}"

  mysqldump \
    -h${HOST} -P${PORT} -u${USER} -p${PASS} \
    $DUMP_BASE_OPTS \
    --databases "$DB" \
    | gzip > "$FILE"

  echo "    -> 完成: $FILE"
done

echo
echo "所有数据库均已成功转储."
echo "输出目录: ${OUT_DIR}"

做到这里，其实“数据有没有丢”这个问题就已经基本不用担心了。

按需导出某一部分数据

接下来遇到的，是更偏实际使用层面的问题。

在整理数据的过程中，经常会有一些很具体的需求，比如：

只需要看某一张表
或者想先筛选一部分数据出来看看

这时候，如果只剩下一堆 .sql 文件，其实并不太好用。

所以我写了一个很简单的 PHP CLI 脚本，用来把一条 SQL 查询的结果直接导出成 CSV。

这个脚本的目标也很单纯：

能处理数据量比较大的表
不一次性把数据全部读进内存
导出的文件可以直接用 Excel 打开

<?php

// 单文件 CLI：MySQL 导出 CSV

if ($argc < 2) {
    echo <<<HELP
Usage:
  php export.php <output_csv_path>

Example:
  php export.php /data/output/users.csv

HELP;
    exit(1);
}

$outputCsv = $argv[1];

// MySQL 配置
$dbConfig = [
    'host'     => '127.0.0.1',
    'port'     => 3306,
    'dbname'   => 'dbname',
    'username' => 'root',
    'password' => 'password',
    'charset'  => 'utf8mb4',
];

// SQL
$sql = <<<SQL
select * from bl_danmu_logs
SQL;


$dsn = sprintf(
    'mysql:host=%s;port=%d;dbname=%s;charset=%s',
    $dbConfig['host'],
    $dbConfig['port'],
    $dbConfig['dbname'],
    $dbConfig['charset']
);
try {
    $pdo = new PDO(
        $dsn,
        $dbConfig['username'],
        $dbConfig['password'],
        [
            PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
            PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false,
        ]
    );
} catch (PDOException $e) {
    fwrite(STDERR, "数据库连接失败: {$e->getMessage()}\n");
    exit(1);
}
$dir = dirname($outputCsv);
if (!is_dir($dir)) {
    mkdir($dir, 0777, true);
}
$fp = fopen($outputCsv, 'w');
if ($fp === false) {
    fwrite(STDERR, "无法写入 CSV 文件\n");
    exit(1);
}
fwrite($fp, "\xEF\xBB\xBF");
$stmt = $pdo->prepare($sql);
$stmt->execute();
$rowCount = 0;
$headerWritten = false;
while ($row = $stmt->fetch()) {
    if (!$headerWritten) {
        fputcsv($fp, array_keys($row));
        $headerWritten = true;
    }
    fputcsv($fp, array_values($row));
    $rowCount++;
    if ($rowCount % 100000 === 0) {
        echo "已导出 {$rowCount} 行\n";
    }
}
fclose($fp);
echo "导出完成，共 {$rowCount} 行\n";

这个脚本更多是用来应对一些临时、零散的导出需求，本身也不复杂。

真正的难点在“交付”这一步

真正让我花时间的，其实是后面这一部分。

如果只是从工程角度看，.sql 已经足够完整；

但从使用角度看，这些数据仍然很难被直接消费。

问题包括：

表很多，一个一个手工导出不现实
Excel 有行数限制，大表没法一次性打开
字段名是英文或缩写，不看表结构根本不知道是什么意思

所以后来我又写了一个脚本，用来把整个数据库的数据，整理成一组 CSV 文件。

这个脚本做的事情也很朴素：

遍历数据库中的所有表
读取字段注释，作为 CSV 的表头
数据量大的表按行数自动拆分文件
所有文件都可以直接用 Excel 打开

这些逻辑都不复杂，只是把原本需要重复做的事情集中到了一起。

<?php

// 单文件 CLI：导出数据库指定表中所有的数据

const MAX_ROWS_PER_FILE = 1000000; // 每个CSV文件最大行数（包含表头）

if ($argc < 3) {
    echo <<<HELP
Usage:
  php export.php <output_folder_path> <database_name>

Example:
  php export.php /data/output/ dabatase_name

注意：每个CSV文件最多包含100万行数据，超过会拆分成多个文件

HELP;
    exit(1);
}

$outputFolder = rtrim($argv[1], '/') . '/';
$dbname = $argv[2];

// MySQL 配置
$dbConfig = [
    'host'     => '127.0.0.1',
    'port'     => 3306,
    'dbname'   => $dbname,
    'username' => 'root',
    'password' => 'zxc7563598',
    'charset'  => 'utf8mb4',
];

$dsn = sprintf(
    'mysql:host=%s;port=%d;dbname=%s;charset=%s',
    $dbConfig['host'],
    $dbConfig['port'],
    $dbConfig['dbname'],
    $dbConfig['charset']
);

try {
    $pdo = new PDO(
        $dsn,
        $dbConfig['username'],
        $dbConfig['password'],
        [
            PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
            PDO::MYSQL_ATTR_USE_BUFFERED_QUERY => false,
        ]
    );
} catch (PDOException $e) {
    fwrite(STDERR, "数据库连接失败: {$e->getMessage()}\n");
    exit(1);
}

// 确保输出文件夹存在
if (!is_dir($outputFolder)) {
    mkdir($outputFolder, 0777, true);
}

// 获取所有表名
try {
    $stmt = $pdo->query("SHOW TABLES");
    $tables = $stmt->fetchAll(PDO::FETCH_COLUMN);
    if (empty($tables)) {
        echo "数据库中没有表\n";
        exit(0);
    }
    echo "找到 " . count($tables) . " 个表\n";
    echo "每个文件最多包含 " . number_format(MAX_ROWS_PER_FILE) . " 行数据\n\n";
    $totalRows = 0;
    $exportedTables = 0;
    $totalFiles = 0;
    foreach ($tables as $table) {
        echo "正在处理表: {$table}...\n";
        // 获取表的字段信息（字段名和注释）
        $commentStmt = $pdo->prepare("
            SELECT 
                COLUMN_NAME, 
                COLUMN_COMMENT
            FROM INFORMATION_SCHEMA.COLUMNS 
            WHERE TABLE_SCHEMA = :database 
            AND TABLE_NAME = :table 
            ORDER BY ORDINAL_POSITION
        ");
        $commentStmt->execute([
            ':database' => $dbConfig['dbname'],
            ':table' => $table
        ]);
        $columns = $commentStmt->fetchAll();
        $headers = [];
        // 准备CSV表头：优先使用注释，没有注释则使用字段名
        foreach ($columns as $column) {
            $columnName = $column['COLUMN_NAME'];
            $columnComment = trim($column['COLUMN_COMMENT']);
            // 如果注释不为空，使用注释；否则使用字段名
            $headers[$columnName] = !empty($columnComment) ? $columnComment : $columnName;
        }
        // 获取字段名数组，用于按顺序读取数据
        $columnNames = array_keys($headers);
        $headerRow = array_values($headers);
        // 查询表数据
        try {
            $sql = "SELECT * FROM `" . str_replace('`', '``', $table) . "`";
            $dataStmt = $pdo->prepare($sql);
            $dataStmt->execute();
            $rowCount = 0;
            $fileIndex = 0;
            $currentFileRows = 0;
            $fp = null;
            while ($row = $dataStmt->fetch()) {
                // 如果是新文件或文件未打开，创建新文件
                if ($fp === null || $currentFileRows >= MAX_ROWS_PER_FILE) {
                    // 关闭之前的文件
                    if ($fp !== null) {
                        fclose($fp);
                        echo "  -> 文件 {$table}-{$fileIndex}.csv 完成 ({$currentFileRows} 行)\n";
                    }
                    // 创建新文件
                    $fileIndex++;
                    $currentFileRows = 0;
                    $outputCsv = $outputFolder . $table . '-' . $fileIndex . '.csv';
                    $fp = fopen($outputCsv, 'w');
                    if ($fp === false) {
                        echo "失败 (无法创建文件: {$outputCsv})\n";
                        break;
                    }
                    // 添加BOM头，确保Excel正确识别UTF-8
                    fwrite($fp, "\xEF\xBB\xBF");
                    // 写入表头
                    fputcsv($fp, $headerRow);
                    $totalFiles++;
                }
                // 按照表头顺序组织数据
                $rowData = [];
                foreach ($columnNames as $columnName) {
                    $rowData[] = $row[$columnName] ?? '';
                }
                fputcsv($fp, $rowData);
                $rowCount++;
                $currentFileRows++;
                // 每 10 万行打一次日志
                if ($rowCount % 100000 === 0) {
                    echo "  -> 已导出 " . number_format($rowCount) . " 行，当前文件: {$table}-{$fileIndex}.csv\n";
                }
            }
            // 关闭最后一个文件
            if ($fp !== null) {
                fclose($fp);
                if ($currentFileRows > 0) {
                    echo "  -> 文件 {$table}-{$fileIndex}.csv 完成 ({$currentFileRows} 行)\n";
                }
            }
            $totalRows += $rowCount;
            $exportedTables++;
            // 确定实际创建的文件数量
            $actualFiles = $fileIndex; // fileIndex从1开始，所以最后的值就是文件数量
            if ($actualFiles > 1) {
                echo "表 {$table} 导出完成: " . number_format($rowCount) . " 行，拆分成 {$actualFiles} 个文件\n";
            } else {
                echo "表 {$table} 导出完成: " . number_format($rowCount) . " 行\n";
            }
            // 重命名单文件情况下的文件名（去掉-1后缀）
            if ($actualFiles === 1) {
                $oldFile = $outputFolder . $table . '-1.csv';
                $newFile = $outputFolder . $table . '.csv';
                if (file_exists($oldFile) && rename($oldFile, $newFile)) {
                    echo "  -> 重命名为: {$table}.csv\n";
                }
            }
            echo "\n";
        } catch (Exception $e) {
            // 关闭可能打开的文件
            if ($fp !== null) {
                fclose($fp);
            }
            echo "失败: " . $e->getMessage() . "\n";
            continue;
        }
    }
    echo "========== 导出完成！ ==========\n";
    echo "成功导出的表: {$exportedTables}/" . count($tables) . "\n";
    echo "总数据行数: " . number_format($totalRows) . "\n";
    echo "生成的CSV文件总数: {$totalFiles}\n";
    // 如果有的表导出失败，列出它们
    if ($exportedTables < count($tables)) {
        $failedTables = array_diff($tables, array_map(function ($csv) use ($outputFolder) {
            return preg_replace('/-\d+\.csv$/', '.csv', basename($csv));
        }, glob($outputFolder . '*.csv')));
        if (!empty($failedTables)) {
            echo "导出失败的表:\n";
            foreach ($failedTables as $table) {
                echo "  - {$table}\n";
            }
        }
    }
    echo "\n文件命名规则:\n";
    echo "- 数据量 ≤ " . number_format(MAX_ROWS_PER_FILE) . " 行: 表名.csv\n";
    echo "- 数据量 > " . number_format(MAX_ROWS_PER_FILE) . " 行: 表名-1.csv, 表名-2.csv, ...\n";
} catch (Exception $e) {
    fwrite(STDERR, "获取表列表失败: {$e->getMessage()}\n");
    exit(1);
}

一点事后的感受

这次整理下来，我的感受其实挺明确的：

技术本身并不复杂
真正需要花心思的，是站在使用者的角度去看数据

对工程师来说，数据库和 SQL 已经很直观了；

但对不直接使用数据库的人来说，Excel 才是他们真正熟悉的工具。

这套脚本对我而言，并不是什么通用方案，只是当时在那个条件下，一种比较顺手、也能把事情做完的办法。

记录下来，也只是给自己以后再遇到类似情况时，留一个参考。

用 Go 像写 Web 一样做桌面应用：完全离线的手机号归属地查询工具

Wed, 17 Dec 2025 08:00:11 GMT

前阵子我做了一个小工具：一个完全离线的手机号归属地查询桌面应用

功能本身其实并不复杂，但在这个过程中，我反而重新认识了一次

用 Go 做桌面应用，其实可以非常像在写一个 Web 项目。

这篇文章不打算讲手机号归属地怎么查（那真的很简单，如果你需要直接到文章底部仓库下载我做好的工具就好），而是想分享一下：

为什么我会选择用 Go + Wails 做成桌面应用，以及这个过程里的一些实际感受。

一个并不复杂的问题

如果不考虑携号转网，手机号归属地这件事本身并不复杂。

每个手机号在规划阶段，前七位就已经确定了对应的：

运营商
省份 / 城市

所以理论上，只要你手里有一份号段库，查询逻辑无非就是：

取前七位 → 查表 → 返回结果

这类数据也并不是什么秘密。

去 GitHub 看一眼，不同语言都有现成的库；百度搜一下，也有不少在线查询网站。

问题不在于“能不能做”，而在于“怎么用得顺不顺”。

为什么现有方案总感觉不太对

在真实使用场景里，我遇到的需求通常是这样的：

机器 不能联网
需要一次性处理 几十万甚至上百万个手机号
只是想快速区分归属地，不想额外搭服务

这时候就会发现：

Web 方案
在线查询适合查一两个号码，但一旦涉及大批量导入（几十上百万的数据）或者涉及隐私问题不方便泄漏这些手机号，就会变得很尴尬。
脚本 / 代码库
不同语言需要不同环境，作为有开发环境的自己用还好，给普通堆代码一窍不通的人用成本就很高了。

我想要的其实是一个很简单的东西：

一个不联网、不装环境，双击就能用的工具。

于是一个想法就冒出来了：

那为什么不直接做成一个 Windows / macOS 的桌面应用？

为什么是 Go + Wails

我之前用 Wails 简单做过一个 PC 端的财务管理应用，但那次更多是“试水”：

Go 当 Web 服务端
Vue 打包进桌面
本质还是一套前后端分离的 Web 思路

这次我反而想换个方式，尽量按照 Wails 的设计方式完整走一遍。

选择它的原因也很直接：

Go
- 编译后就是一个可执行文件
- 非常适合做本地工具
- 处理本地数据、文件都很舒服
Wails
- 用 Web 技术写桌面应用
- 不需要起 HTTP 服务
- 前端可以直接调用 Go 方法

我平时用 Vue 比较多，所以直接用：

wails init -n 项目名 -t vue

Wails 支持的模板其实不少，React、Vue、Svelte 都有，翻一翻文档基本都能找到，这里就不展开了。

和传统 Web 最大的不同：没有路由

如果你是做 Web 开发的，上手 Wails 会非常快。

传统 Web 项目里，我们习惯的是：

Router（路由） → Handler（HTTP处理器） → Service（业务逻辑层） → Repository（模型访问层） → Model（数据模型）

请求通过路由分发到 Handler，再一层层往下走。

而在 Wails 里：

不需要路由
app.go 里的方法，会自动暴露给前端
前端直接把它当成一个函数来调用

换个角度看：

app.go 里的方法，其实就相当于传统 Web 里的 Router + Handler

至于 Service、Repository、Model 这些分层，完全可以照搬。

只是“请求”不再是 HTTP，而是一次本地方法调用。

这个点让我感觉非常舒服：

开发思路几乎没变，只是把“接口”换成了函数。

48 万条数据，SQLite 该怎么放

这个项目里有一个比较现实的问题：

我内置了 48 万多条手机号号段数据。

SQLite 本身非常适合这种场景，但如果在应用启动时再一条条初始化写入数据库，体验会非常糟糕。

所以我的做法是：

提前生成一个完整的 .db 文件
在构建时，通过 embed.FS 把这个数据库文件带进程序
程序启动时：
- 如果用户本地还没有数据库
- 就直接把这份已经初始化好的 .db 拷贝过去

这样一来：

启动速度很快
不需要额外初始化逻辑
数据也完全可控、可更新

这一步做完，后面的事情就简单很多了。

当然，考虑到数据会更新，我预留了构建脚本，方便开发过程中构建这个 .db 文件

开发体验：真的很像在写 Web

剩下的开发过程，基本就是“Web 开发的本地版”：

Go 这边写好查询服务
在 app.go 封装成方法
前端直接调用，不需要网络请求
wails build 一次性完成：
- 前端打包
- 后端编译
- 桌面应用生成

项目放在 GitHub 上之后，再配合 GitHub Actions，就可以自动构建 Windows / macOS 的可执行文件，整个流程非常顺。

一个很小的项目，但这个思路很实用

这个项目本身并不复杂，代码量也不多，我也尽量写了比较完整的注释。

如果你：

想试试 用 Go 写桌面应用
又或者只是需要一个 离线的手机号归属地查询工具

都可以看看这个项目，或者直接下载编译好的程序来用。

项目地址在这里：

👉 https://github.com/zxc7563598/go-mobile-locator

有时候换一种“应用形态”，

反而能让很多原本别扭的问题，一下子顺起来。

用 PHP 解析 Protobuf 的坑与解法

Fri, 12 Dec 2025 06:59:01 GMT

前阵子做的一个直播弹幕的机器人，其中有一部分上游数据是通过 Protobuf 返回的。几个朋友问我怎么处理，但我发现大家对「PHP 解析 Protobuf」这件事多少有点迷糊。确实，PHP 处理 Protobuf 的资料不多，而且踩坑成本不算低。

这篇文章不打算科普什么，也没有推荐任何技术栈的意思，就是把我自己摸索的过程整理出来，给遇到类似问题的人一个参考。

Protobuf 是什么

很多人第一次接触它时，会把它和 JSON、XML 放在一起理解，但 Protobuf 并不是“另一个 JSON”。它是一种 基于 Schema 的二进制数据格式，本质上由两个部分组成：

.proto：数据结构的描述文件（类似字典）
二进制格式：根据 .proto 规则编码出来的数据

Google 发明它的原因大致是：

JSON 太大、太慢
在高性能、跨语言通信场景里不够理想
服务端内部大量 RPC 调用时，序列化效率太重要了

于是有了 Protobuf：数据格式紧凑、序列化速度快、跨语言支持也强。

它不是为了可读性，而是为了性能。

PHP 解析 Protobuf 为什么麻烦

PHP 能解析 Protobuf，但体验不如其他语言。原因有几个，简单列一下：

PHP 无法动态解析 Schema

像 Go、Python、Java 这类语言可以依靠 descriptor 动态解析 Protobuf 数据结构，甚至可以在运行期处理未知结构。

PHP 目前做不到，没有暴露那一套 API。

所以 PHP 必须依赖 .proto 文件，并且必须提前用 protoc 生成对应的 PHP 类。

PHP 的 Protobuf 扩展是“最小实现”

google/protobuf 的 PHP 扩展只提供：

序列化：serialize
反序列化：mergeFrom
基本的 getter/setter 机制

其他高级能力基本没有。

PHP 的生态也不会把“解析二进制协议”当作主要用途

PHP 的常见使用场景偏 Web，因此处理二进制协议并不是重点。

并不是我们主动选择 Protobuf

在一些服务里，上游服务已经定死使用 Protobuf；或者 PHP 服务只是边缘网关，需要解析一次再转发。

在这种情况下，只有硬着头皮支持。

如果是自己的项目，并没有强约束，其实 JSON 足够了。

PHP 如何使用 Protobuf

我自己在服务器上没有安装 Protobuf 扩展，而是采用更常见的一种方式：

本地安装 protoc
用 .proto 文件生成 PHP 类
服务器端只需要安装 google/protobuf 包即可完成解析

第一步：安装运行时库

composer require google/protobuf

这是 PHP 解析 Protobuf 所需的唯一运行时依赖。

第二步：安装 protoc（在本地）

protoc 是官方编译器，用于把 .proto 文件生成各种语言的类（包括 PHP）。

下载地址：

https://github.com/protocolbuffers/protobuf/releases

选择对应平台的压缩包，解压后把 protoc 放到 PATH 中即可。

验证是否安装成功：

protoc --version

.proto 文件是什么

.proto 文件可以简单理解为“数据结构的一份字典”。

因为 Protobuf 的二进制格式里没有字段名，只有字段编号（tag）。

例如：

field #1:  123
field #2: "Alice"

你不知道 #1 是 id 还是 age，也不知道 #2 是 name 还是别的东西。

所以必须依靠 .proto 文件才能解码。

使用 protoc 生成 PHP 类

我本地的命令大致如下：

protoc --php_out=./protobuf \
       --proto_path=./protobuf \
       xxx.proto

含义如下：

--php_out：生成的 PHP 文件存放位置
--proto_path：寻找 .proto 的目录
多个 .proto 可以一起编译

protoc 会根据 .proto 内容生成一堆 PHP 类，每个 message 对应一个 PHP 类，最终这些类会继承：

Google\Protobuf\Internal\Message

序列化、反序列化功能都来自这个基类。

配置 Composer autoload

如果你希望通过命名空间加载生成的类，可以在 composer.json 中加一条：

"autoload": {
    "psr-4": {
        "Proto\\": "protobuf/"
    }
}

然后执行：

composer dumpautoload

在 PHP 中解析 Protobuf

解析的核心方法是：

$msg->mergeFromString($binary)

读完后，数据结构会自动填充在 message 对象里。

在 PHP 中生成 Protobuf 数据

序列化对应的方法是：

$binary = $msg->serializeToString();

得到的就是一段 protobuf 二进制字符串，可以直接发送到网络或写入文件。

快速测试

创建一个项目，目录结构如下：

.
├── protobuf
│   └── TEST_USER_INFO.proto
└── test.php

TEST_USER_INFO.proto

syntax = "proto3";

option php_namespace = "TestUserInfo";

message User {
  int32 id = 1;
  string name = 2;
}

test.php

<?php

require __DIR__ . '/vendor/autoload.php';

use TestUserInfo\User;

$u1 = new User();
$u1->setId(7);
$u1->setName("PHP Encode Test");

$bin = $u1->serializeToString();

$u2 = new User();
$u2->mergeFromString($bin);

var_dump([
    '原始数据' => bin2hex($bin),
    'id' => $u2->getId(),
    'name' => $u2->getName(),
]);

安装运行时库

composer require google/protobuf

编译 .proto 文件

protoc --php_out=./protobuf --proto_path=./protobuf TEST_USER_INFO.proto

这会在 protobuf/ 目录下生成 PHP 类文件，供 PHP 使用。

配置 Composer autoload

在 composer.json 中增加命名空间映射，例如：

{
  "require": {
    "google/protobuf": "^4.33"
  },
  "autoload": {
    "psr-4": {
      "GPBMetadata\\": "protobuf/GPBMetadata",
      "TestUserInfo\\": "protobuf/TestUserInfo"
    }
  }
}

然后重新加载 Composer 自动加载：

composer clear-cache && composer dump-autoload -o

运行测试

php test.php

运行后，你会看到序列化再反序列化的数据被正确输出，证明 PHP 成功处理了 Protobuf 数据。

写在最后

PHP 解析 Protobuf 的体验确实不算好，但能用，并且在某些需要兼容上游服务的场景里还是必须用。
如果你也正在处理类似的数据，希望这篇文章能帮你少踩点坑。

如果感觉文章里哪部分还没说清楚，欢迎继续交流。

从零开始做 Go 项目：我的目录设计分享

Mon, 01 Dec 2025 14:44:37 GMT

为什么要先规划目录结构

刚开始写 Go 项目的时候，我对目录结构这件事格外重视。对于刚入门的人来说，开发过程中几乎每件事情都是第一次：

全局配置怎么放？
数据库连接怎么初始化？
Model 怎么设计？
路由怎么组织？

每一个点都能让人迷茫。

相比之下，像 Java 的 Spring Boot 或 PHP 的 Laravel 都会给你一套“默认结构”，至少能让你知道应该往哪里放东西。

而 Go 更自由，没有强迫你必须怎么做。对老手是好事，对新手却可能会踩坑。

我的经验是：

合理的目录结构 = 清晰的思路 + 舒适的开发体验

规划好结构之后，你可以把问题拆开逐个去实现，而不是一上来就面对一坨混乱的代码。

我的 Go 项目目录结构（Gin 示例）

下面是我常用的目录结构，适合大多数中小型 Web 项目：

.
├── cmd/              # 项目入口目录
│   └── main.go       # 主程序入口
├── internal/         # 私有代码目录
│   ├── dto/          # 结构体定义目录
│   ├── handler/      # HTTP处理器(等同于Controller)
│   ├── model/        # 数据模型
│   ├── repository/   # 数据模型访问层
│   ├── router/       # 路由
│   └── service/      # 业务逻辑层
├── pkg/              # 可被外部引用的包
│   ├── config/       # 配置
│   ├── i18n/         # 国际化
│   ├── jwt/          # jwt
│   ├── middleware/   # 中间件
│   └── utils/        # 工具函数
├── api/              # API文档(Swagger)
│   └── swagger.json
├── scripts/          # 构建、部署脚本目录
├── go.mod
├── LICENSE
├── Makefile          # 自动化脚本说明书
└── README.md

cmd/：项目入口

cmd 存放整个项目的入口程序。

通常项目只有一个：

cmd/
└── main.go

如果未来拆成多个服务（如 API + Worker），结构可以扩展成：

cmd/
├── api/
│   └── main.go
├── worker/
│   └── main.go

这样多服务更好管理。

internal/：项目私有代码

internal 是 Go 官方定义的 私有代码机制：这里的包只能本项目引用，外部无法导入。

我会把它拆成几个层次，职责分明：

internal/
├── dto/          # 请求/响应结构体
├── handler/      # HTTP 层
├── service/      # 业务逻辑层
├── repository/   # 数据访问层
├── model/        # 数据模型
└── router/       # 路由注册

调用链是单向的：

Handler → Service → Repository → Model

下面简单说一下每层负责什么：

Handler：接收/解析请求，参数校验，调用 Service
Service：业务逻辑处理
Repository：数据库读写（纯 CRUD，不写业务）
Model：数据库结构体
DTO：请求/响应结构（隔离 Model）
Router：注册路由，绑定 Handler

这种分层结构很适合 Go，也比 PHP 那种“一个 controller 干到底”的写法更好维护。

另外，Go 的一个特点是：

同一个 package 下多个 .go 文件对编译器来说等同于同一个文件。

所以可以自由地按模块拆成多个 user.go、order.go，对程序来说他们直接就是一个文件不会有任何影响，但分开之后代码的可读性会极大的提高。

如果你有其他面向对象语言的经验，Go会带来全新的编程体验。核心的思维转变可归纳为四点：

忘掉"类" → 记住"结构体+方法"
忘掉"继承" → 使用"组合+接口"
忘掉"设计模式套用" → 关注"解决问题"
接受显式错误处理 → 不再有try-catch

pkg/：可复用的公共包

pkg 用来放可被其他项目引用的通用模块，例如：

pkg/
├── config/
├── i18n/
├── jwt/
├── middleware/
└── utils/

如果只是给当前项目用，不需要放在 pkg，尽量归到 internal。

另外也建议不要堆一个“大 utils”，按功能拆分更容易维护。

api/：API 文档

这里一般放 Swagger / OpenAPI 的定义文件（JSON/YAML）。

用这些工具来管理接口文档可以：

自动生成文档
保持前后端对齐

对于多人协作非常有用。

Makefile：常用命令的“快捷键”

我一般会把常用命令写进 Makefile，比如：

run:
    go run cmd/main.go

build:
    go build -o bin/app cmd/main.go

test:
    go test ./...

Makefile 是个好东西，你可以把各种项目会用到的命令像清单一样列出来。

如果你有心思，甚至可以去做一个 help 命令来告诉其他人都有什么命令

help:
	@echo "可用指令："
	@echo "  make deps          # 安装 / 更新 Go 依赖"
	@echo "  make fmt           # 统一格式化后端 Go 代码"
	@echo "  make test          # 执行全部 Go 单元测试"

对新同事非常友好，哪怕不了解项目，也可以通过阅读 Makefile 快速上手项目。

总结

对我来说，一旦目录结构定下来，剩下的基本就像做“填空题”一样：

中间件怎么写
JWT 怎么做
数据库要建哪些表
Handler / Service / Repository 各自实现哪些逻辑

这些都能一块一块稳稳推进。

Go 社区里没有唯一正确的结构，但这套分层思路对新手来说非常友好，也足够应对大部分项目。

如果你正在准备写一个 Go 项目，希望这套结构能帮你少踩一些坑，也让你的项目更容易维护。

MineContext：我第一次感觉 AI 真正在“主动帮我管理生活”

Thu, 20 Nov 2025 16:28:43 GMT

我现在一天基本离不开 AI 了。
不是那种“把提示词写得像炼丹”式的依赖，而是很平常的那种：

我写代码，它在旁边检查。
我整理逻辑，它帮我捋一遍。
我写文档，它补补关键字、给点建议。

整个过程更像是 我在人前台写，它在后台兜底。
它不是替我工作，它是把我的工作做得更圆滑、更完整。

但说实话，我过去对“AI 助理”的期待真的不高。
因为不管助理多聪明，你不给输入，它就是个哑巴。

它更像一个“贴心的编辑器”，而不是一个“主动的助理”。
尤其是写日报、周报的时候。

我不说，它啥都不知道。
输入少，它就笨；输入多，我就累。

所以一般都是：

我亲自写 → AI 润色 → 我审核 → 再调整一下。

直到我遇到了 MineContext。

直到我遇到 MineContext

有一天我随便逛 GitHub，看到一个叫 MineContext 的东西。
它确实在某种程度上展示了某种 AI 使用的新方向。

它不是等你给材料，它是：

自己看
自己分析
自己整理
自己总结
最后把报告端过来

我只是正常用电脑，它就在后台默默观察。

等我晚上坐下来，它就会递给我一份报告，告诉我今天都做了什么。

那份报告甚至比我自己写的更全面、更有逻辑、更有洞察。

对于我这种喜欢把生活“数字化”来管理的人来说，这东西简直是天赐。
我甚至隐隐觉得，这可能会成为新一代人的工作方式。
AI 主动帮你记录、帮你整理，而不是你逼着自己记。

MineContext 到底在干什么？

用人话讲，它平时就在干这几件事：

定时截图你的屏幕

比如每隔几秒，它截一张当前屏幕。

用视觉模型分析你在干嘛

它能识别页面、文档、代码、聊天窗口、IDE、网页内容……
然后把这些内容结构化。

比如：

你在写 PHP
你在查某个 Cloudflare 500 报错
你在写博客
你在看一个项目的 README
你在 debug
你在管理数据库
在跟桐桐聊天，她说她外公喝的茶 1680 一斤，你下单三斤并约定下周一面交（咳）

自动去重、过滤、归类

把无意义的截图清理掉，把重复信息合并掉，不会让你的数据变垃圾堆。

每一小段时间自动做小结

像一个实时存在的“精简时间线”。

生成洞察报告

每天、每周，它会把你这些碎片化行为整理成一份真正可读的报告。

内容包括：

你今天主要在做什么
处理了哪些任务
花了多少时间
今天的重点主题是什么
有哪些工作模式、习惯、偏好
今天的 highlights / issues
有时候甚至会给你建议

读起来真的就像把自己交给了一个观察者，它在旁边默默记录你的一天，晚上把故事整理好给你。

为什么我说它是 ADHD 神器

我不是专业讲 ADHD 的，就是站在“注意力容易飘”的普通人角度说一下。

很多人应该都有这种感觉：

做了很多事，但回头想不起来今天干了啥
一天结束的时候没成就感
事情都是碎片的，很难拼成完整的故事
想写日报时经常“空白”
想复盘一下，发现自己根本想不起来

MineContext 的价值就在这里：

它帮你把碎片变成结构。

白天你专心干活，无脑沉浸。
你不需要特地记，也不需要刻意整理。

到了晚上，它已经把你的：

工作流
切换记录
查资料轨迹
输入输出
项目参与
日间行为模式

全部整理得清清楚楚。

它甚至会告诉你：

你今天对某个任务持续投入了 2 小时
你某段时间反复在查某个问题
你的注意力什么时候最集中
你什么时候容易走神

这对注意力问题人群来说太有用了。

基本上你只需要“活着”，它帮你记录你的生活

这东西意味着什么？

我觉得 MineContext 展示了一个非常新的方向：

AI 正在从“你问我答”，变成“我帮你先做”。

这是一种新工作方式：

人类负责体验、创造、执行
AI 负责记录、整理、总结、复盘

这和我们之前用 AI 的方式完全不一样。

以前是：

我要你帮我做点事 → 我提供输入 → 你输出

MineContext 是：

我在过我的一天 → 它收集输入 → 它输出给我 → 我再决定怎么用

这带来的变化非常大：

你不必靠记忆工作
你不会错过工作中的关键行为
你能轻松复盘
你的大脑不再负责“记”，它只负责“想”

甚至我隐约觉得：

将来老板可能会用这种东西来监控员工……

（真的完全不是不可能，毕竟这玩意可以很精确地记录行为模式）

不过目前我并不是很担心这一方面，毕竟它是开源的，控制权在你。

而且数据都是存储在本地，并不会上传云端，每次启动也都需要你自己手动开启才可以。

所以可能老板会更容易从社会学层面入手，比如半夜偷偷溜回公司开你电脑看你一天摸鱼跟朋友八卦的快速总结

最后的感受

我现在几乎每天晚上都会看它给我生成的日报。
那种体验很奇妙。

明明是一整天的琐碎行动，它却能被整理成一个“像故事一样”的东西：
有结构、有因果、有线索、有意义。

它记录的不是任务列表，而是你的节奏、注意力、思考方式、行动轨迹。
感觉真的像是和另一个自己一起观看生活的回放。

这让我突然意识到：
AI 不是在帮我工作，而是在帮我“理解我自己”。
而理解自己，恰恰是现代人最缺的能力。

这几年，AI 热潮来得太快了，快到许多人的态度开始走形。

有人把 AI 神化，觉得它能给人带来超越常识的答案；
有人带着宗教式的期待，把提示词当作咒语，把模型当成神谕；
哪怕一次输出不准，也会怪自己“仪式没做对”，再换一次说法，再祈祷一次。

那种感觉有点像对未知祈祷：
一半期待救赎，一半害怕怪异。
而在这种矛盾里，人反而越来越看不清自己。

但我越来越觉得，拒绝 AI 和迷信 AI，本质上都是 放弃了自己的主体性。

MineContext 的好在于，它的介入方式非常温和。
它不是来替你做决定的，也不会告诉你应该怎么活。
它只是默默观察、整理、复盘，把信息用你的方式还给你。

它像一面镜子，但这面镜子比你自己多看到一点点：
看到你忽略的细节、看到你一天当中的节奏、看到你无意间形成的路径。
它帮你把混乱变成秩序，把碎片变成轨迹，把流水账变成有意义的叙事。

你还是你，只是更清晰了一点。

在未来这个 AI 会越来越深入环境、工作、家庭，甚至身体的时代里，
我觉得从这种工具开始，让 AI 以一种不侵入的方式参与生活，是一种很好的提前适应。

你不会迷失自己，也不会落在潮水后面。

如果你也想体验一下，GitHub 下载下来，填上自己的 API Key，就能直接用：MineContext

写博客写代码都适用：推完就自动部署的 GitHub Webhook 工具

Wed, 19 Nov 2025 16:57:47 GMT

前阵子，我看到有人在吐槽自己写博客很麻烦——写麻烦、托管麻烦，推完 GitHub 之后还得去服务器上手动拉代码部署。虽然我以前在做类似的东西，但他这么一提让我想起这件事，我就想着，不如把自己一直随便用的小玩意整理一下，顺便分享给大家。

于是就有了这个小项目：一个轻量级的 GitHub Webhook Listener，用 Go 写的，可以帮你在推送代码后自动触发部署。

什么是 Webhook

Webhook 本质上就是 GitHub 在某些操作发生时，向你指定的地址发送一个网络通知。最常见的事件包括 push、pull_request、release 等。收到通知之后，你就可以根据事件类型做一些操作，比如自动部署代码、触发测试、更新文档等等。

设置 Webhook 其实也很简单：在 GitHub 仓库里找到 Settings → Webhooks → Add webhook，填入你服务器的地址和一个 Secret，选中你想监听的事件，然后 GitHub 就会在这些事件发生时发送 POST 请求到你的服务器。只要你的服务端能接收请求、校验 Secret，再执行对应操作，就完成了。

我以前一直随便把 Webhook 放在某个在跑的服务里处理，所以一直没有好好整理过。Webhook 的核心其实不复杂，它需要的只是一个接口去接收请求，这也是之前一直随手搞的原因。

为什么选 Go

Go 写这种小工具特别合适：

编译后就是一个二进制文件，直接丢到服务器上运行就行，不依赖其他环境。
运行开销小，启动快，非常适合长期驻留监听请求。
写起来简单，核心逻辑就是解析 HTTP 请求、验证签名、匹配事件和分支，然后执行命令。

所以我就决定用 Go，把这个小工具整理出来。你只需要放一个简单的配置文件，二进制程序就能运行起来。

配置示例

配置文件大概长这样：

repos:
  'zxc7563598/astro-theme-pure': # 仓库名称
    secret: 'xxxxxx' # GitHub Webhook Secret
    rules:
      - event: 'push'
        branches: ['main']
        actions:
          - type: 'shell'
            command: 'sh ./shell/astro-theme-pure.sh'

程序启动后会在指定端口监听请求，收到事件就去匹配分支和事件类型，如果匹配，就执行你配置好的 shell 脚本。

就好像上面的配置，当 zxc7563598/astro-theme-pure 仓库的 main 分支触发了 push 时，脚本就会去执行 sh ./shell/astro-theme-pure.sh。

这样一来，你只管写代码，部署流程就自动完成了。

我的部署脚本

我博客的部署脚本大概是这样：

#!/bin/bash
set -e
PROJECT_DIR="/opt/astro-blog"
GIT="/usr/bin/git"
BUN="/usr/bin/bun"
PM2="/usr/bin/pm2"
export HOME="/root"
export PM2_HOME="/root/.pm2"

log() {
    echo "[deploy] $1"
}
log "========================================"
log "开始部署 Astro Blog"
log "时间: $(date)"
log "========================================"
cd "$PROJECT_DIR" || { log "无法进入项目目录"; exit 1; }
log "拉取最新代码..."
$GIT fetch origin
$GIT reset --hard origin/main
log "安装依赖（Bun）..."
$BUN install
log "构建 Astro 项目..."
$BUN run build
log "重启 PM2 进程..."
$PM2 restart "$PROJECT_DIR/ecosystem.config.cjs"
log "PM2 状态："
$PM2 list || true
log "部署完成"
log "时间: $(date)"
log "========================================"

有了这个流程，我写博客只管写代码，编辑器里写完 push，一切自动完成。服务器自己去拉取、构建、重启，我几乎不用管。

如果你也想试试

这个小项目我整理在 GitHub 上了：github-webhook-listener。它轻量、灵活，上手也很快。如果你也想搞个自动部署，可以直接拿去试试，不用在意具体实现或代码，看看 README，或者直接在 releases 里下载就能用。

自动化我的友链申请脚本：让孤岛互相连起来

Fri, 14 Nov 2025 10:59:33 GMT

友链这东西，说出来有点浪漫。

2025 年了，个人博客基本没有什么流量，更多像是一座座散落在海上的小岛。
偶尔有海风吹过，但大多数时候，就是悄悄发光、自娱自乐。

而友链……就像是在这些小岛之间铺上一条条细细的桥。
你看不到桥的尽头，但知道那里至少还有一个同样孤独、同样固执的人。

为什么拖了这么久才开放友链申请？

刚写博客那阵子，我其实没太敢申请友链。不是因为不想被发现，而是因为我真的是那种比较内向的类型。

内容少也不自信，总觉得“我这样去申请友链，会不会显得很冒失？”
再加上每个人对友链的理解都不太一样：

有人只收特定领域的高质量博客
有人觉得必须线下认识
也有人坚持要有一定的线上互动次数

即便对方没有列要求，我心里还是会嘀咕：“我们不熟，贸然提出会不会不太礼貌？”

传统的友链申请方式大多是：留言、邮件，或在 GitHub 提 issue。看似简单，但对我这种“有自助收银台绝不走人工”的 I 人来说，其实是需要一点点勇气的。

直到有一次，我在看一位老师的博客时，看到有人问：“这么多友链，你是怎么维护的？”
老师回： “脚本。”

那一瞬间我有点被点醒了：
既然我不好意思主动打招呼，那是不是可以先让别人跟我打招呼不要那么困难？

说干就干：自动化友链要处理些什么？

为了做到“自动添加”，其实需要处理的事情很简单：

对方网站必须能访问
不能让广告站点钻空子
对方真得挂上了我的友链

于是我要求申请方提供友链页地址，然后脚本负责验证：

确认主站是正常可访问的
主站域名与友链页域名一致（避免广告跳转）
友链页中确实存在我的网站

通过就添加，没通过就直接拒绝，简单粗暴但有效。

技术实现：我是怎么做的？

1. 友链数据剥离成 JSON（重点）

一开始我的友链是写在 Astro 的页面里的。
但这意味着：

改一个字 → 就得重新打包部署

非常麻烦。

后来改用 SSR（服务端渲染） 后，我意识到：

完全没必要把友链打包进页面里。
数据完全可以在服务端“即时读取”。

于是我把友链抽成一个 links.json 文件，并且 不再使用 import 引入它。
因为一旦 import，它就会在构建时被写死。

正确的方式是：

const raw = await fs.readFile(linksPath, 'utf-8')
const { friends } = JSON.parse(raw)

这样：

JSON 是独立的数据源
SSR 每次渲染页面都会读取到最新内容
修改 JSON = 友链立即生效
无需重新打包

这也是我把友链从页面剥离出来的根本原因。

2. 头像检查 + 上传 OSS

用户提交的头像链接永远无法保证靠谱：

有的不是图片
有的没 content-type
有的会失效

我的解决方案是：

先判断扩展名是否是图片
再通过请求检查 content-type
最后统一上传到 OSS

我用的是 ossutil

因为它是 CLI，不需要把 AccessKey 写进代码里，对我这种 Node 不熟练的人来说更安全。

（当然也可以不用 OSS，不过不管是速度还是稳定性都不如 OSS 省心）

3. 检查对方是否挂了我的链接

为了避免“我挂你，你不挂我”或者广告的情况出现，脚本会：

访问对方主站
检查友链页是否同域
抓取页面，看是否包含我的链接

确认通过，才会添加。

4. 自动更新 JSON + 顺手 Git 提交

友链通过验证后，脚本会：

把条目写入 links.json
自动执行 git add → commit → push

因为是 SSR，页面下一次请求时就会看到最新的友链数据。

不需要重新打包，也不需要重新部署。

整个流程非常轻量。

SSR 这个环节的重要性

在写脚本之前，我也想过纯静态博客能不能实现自动化友链。
答案是：能，但非常折腾，不值得。

纯静态的问题：

页面打包后就是死的，无法在服务端执行校验逻辑
用户无法直接让服务器写入文件
想走 GitHub Actions，需要用户先有权限 push（显然不行）

虽然理论上可以：

表单提交 → 云函数写文件 → 云函数 push GitHub → Actions 构建 → 部署

但整个链路太长太容易出问题。

相比之下：

SSR：写一个 API 就全部搞定

Cloudflare、Vercel 都能跑 SSR
甚至没服务器也能跑

所以最后我还是选择了最干净、最好理解、扩展性最高的方案：
在 SSR 里加一个接口，让它帮我跑脚本、改 JSON、推 Git 就完事了。

最后的一点小感慨

整个自动化流程，说白了，就是给像我这样的 I 人一点点缓冲空间。

我非常尊重那些坚持手工审核友链的朋友

那是对自己博客节奏和边界的坚持，我完全理解。

但我也知道，有不少朋友可能跟我一样：

觉得对方的博客不错
想互相交换友链
却迟迟按不下那个“开口”的按钮

这个脚本解决不了我鼓起勇气去申请别人友链的问题。

但至少 如果你也是这样的 I 人，来我的博客交换友链时，你完全可以毫无心理负担

如果你想看完整的代码与改动，可以看这里：
👉 点击查看

被问性能后，我封装了这个 PHP 错误上报工具

Tue, 11 Nov 2025 15:34:05 GMT

最近我把自己常用的一套错误上报逻辑封装成了一个 Composer 包，叫 hejunjie/lazylog。
功能很简单也很实用：安全地写本地日志 + 把异常信息上报到远端（支持同步/异步） 。本文讲讲为什么我要做这个库、实现思路、在不同运行环境下如何选择（以及我推荐的优化方案）。

起因：为啥要做这个工具？

先讲个背景。之前我写了一个 Go 项目 —— oh-shit-logger，目标是把不同语言、不同项目里的错误集中收集到一个地方。Go 做服务天然快、部署也简单： GitHub Actions自动打包，我只要把包丢主机上一键启动就好了。

但上线后有朋友问：

“PHP 上报错误会不会太耗性能？网络 I/O 会不会成为瓶颈？”

这是个很合理的问题。网络 I/O 的确有成本，但异常本身在多数系统里不是那种持续不断、高频率的事件（如果异常多到经常并发，那系统可能已经在出问题了）。

与其空谈“会不会慢”，我更愿意把常用做法封装一下，直接给出一个实战好用的方案——于是 hejunjie/lazylog 诞生了。

思路概览：伪异步 + 可回退的同步

lazylog 的核心思路很简单：

本地写日志：线程安全、支持按行数/大小自动切分，长期运行不会把单个日志文件撑爆。
远程上报：提供两种方式：
- 异步上报（伪异步） ：通过 proc_open() 或 exec() fork 出一个 PHP CLI 子进程来发送 HTTP POST，不阻塞主进程。适用于 PHP-FPM、一次性 CLI 脚本等短生命周期环境。
- 同步上报：直接在当前进程做一个带超时的 HTTP POST，适合常驻内存框架（Webman、Swoole、RoadRunner 等）或需要保证上报结果的场景。

我把这些行为都封装在一个很小的包里：composer require hejunjie/lazylog，在任何项目里都能快速复用。

异步实现细节：为什么是“伪异步”？

PHP 没有内置线程（除非用扩展），但我们可以通过子进程实现“非阻塞式”的上报：

proc_open()：启动子进程并可拿到 stdin/stdout/stderr，控制能力强；但会创建管道资源，需要注意关闭管道以免资源泄露。
exec()：简单粗暴，把命令交给 shell 去做 fork，父进程可立即返回（命令后面加 &）。语义上更轻量，但控制能力弱。

两者的本质都是 fork 一个新进程去跑 PHP CLI，然后子进程读取临时文件（或者接收传参）、发 POST、删临时文件、退出。主进程不会等子进程走完就返回给用户，所以对用户体验几乎零影响。

优点：实现简单、跨平台、即插即用；适合错误信息本身不高频的场景。
缺点：在“极高并发”场景下（比如每秒上千条错误）会比较吃资源，子进程启动和网络请求仍然有成本。

常驻内存框架（Webman/Swoole）该怎么办？

这是个重要的实践问题：在常驻内存框架中，我更推荐用同步上报或队列，而不是频繁 fork 子进程。

原因很直观：

常驻框架的 Worker 是长期存在的，fork 子进程会带来额外的资源管理问题（僵尸进程、内存增长、文件描述符等）。
同步上报虽然会阻塞当前 Worker，但只影响当前 Worker，不会像在传统短生命周期中影响整个请求模型。对于大多数低频异常而言，这个阻塞代价是可以接受的。
更稳妥的做法是：把异常先格式化成数组，投递到队列，由专门的队列 worker 来异步上报。这样既避免了直接 fork，又能在不影响主流程的情况下批量/可靠地上报。

我在包里同时提供了 reportSync()（同步上报）和 reportAsync()（伪异步上报），并提供 Logger::formatThrowable() 帮你把异常转成纯数据结构，方便推队列或序列化。

实际使用示例

这里只放伪代码以示意，实际代码见仓库。

本地写日志

Logger::write('/var/logs', 'error/app.log', 'Task Failed', ['msg' => 'something wrong']);

短生命周期场景（异步上报）

try {
  // ...
} catch (Throwable $e) {
  Logger::reportAsync($e, 'https://your-collector/collect', 'my-project');
}

常驻框架（推荐同步或队列）

try {
  // ...
} catch (Throwable $e) {
  // 同步上报（简单、直接）
  Logger::reportSync($e, 'https://your-collector/collect', 'my-project');

  // 或者：转成数组，投递队列，由 Worker 负责上报（推荐）
  $payload = Logger::formatThrowable($e, 'my-project');
  Queue::push('error_report', $payload);
}

性能那些事儿

有人担心“网络 I/O 会把 PHP 卡死”。我的观点是：

错误本身通常是低频事件。如果你的系统错误频率高到持续占用大量带宽/请求，那说明系统正常运行已经有更严重的问题了。
对于多数业务，一次 fork 一个子进程并做一次 HTTP POST 的开销在可接受范围，用户体验影响极小。
在对性能要求极苛刻或错误量非常大的场景，正确做法是把上报变成队列 + 批量发送或将上报移动到专门的后端处理链路，而不是在业务路径里频繁 fork。

总之：衡量利弊后选择适合你业务的方式。lazylog 提供了两端（sync/async）以及格式化功能，方便你按需设计。

最后

我把它做成 composer 包的原因很直接：我希望 快速把 PHP 项目的错误上报到我自己的 Go 服务（oh-shit-logger） ，而不是每个项目都重复造轮子。把常用逻辑抽出来，项目里 composer require hejunjie/lazylog 就能统一上报方式——既省事又稳妥。

如果你想快速了解这个项目：Zread 解析文档

如果你是在 PHP-FPM / CLI 的短生命周期环境：reportAsync() 很方便，能保证主流程不被阻塞。
如果你是在 Webman/Swoole 等常驻内存框架：优先考虑 reportSync() 或推队列再上报。
如果你面临的是极高并发的错误量：把上报放队列，批量发送，或交由专门的采集基础设施处理。

Astro 博客加密教程：保护文章内容的 SSR 方案

Sun, 09 Nov 2025 16:31:02 GMT

为什么想要加密文章

有时候我们希望自己的博客文章不是所有人都能直接看到，最好能设置一个问题验证——只有答对的人才能解锁内容。
听起来简单，但对于纯静态博客来说，这其实挺麻烦的。

静态博客的“加密”假象

静态博客的所有内容，在构建时就已经写进了 HTML 里。
即使你用 CSS 或 JavaScript 把文字“藏”起来，用户打开浏览器开发者工具就能轻松看到原文。

有人会选择在前端加密文章内容，然后在浏览器里解密再显示。
这个办法能提高一点门槛，但问题是——加密密钥也在前端，意味着别人仍有办法找到它。

真正安全的做法，不是去“隐藏内容”，而是让验证和解密都发生在服务器上，浏览器只负责展示。

SSR：给静态博客加上“动态大脑”

当博客切换到服务端渲染（SSR）后，文章内容就不会提前打包到前端，而是在请求时由服务器生成。

这样做的好处显而易见：

内容不再暴露在 HTML 里
可以在服务端验证访问条件
访问控制逻辑更清晰、可扩展

所以我的思路是：用 SSR + 接口验证 的方式，实现文章加密。

实现思路概览

我把整个流程拆成了几个部分来实现，使用的主题为：astro-theme-pure

其余的主题依然可以用本文思路实现

1. 从静态输出改为 SSR

将 astro.config.ts 里的 output: 'static' 改为 output: 'server'。

在我使用的 astro-theme-pure 主题的配置文件中已经预设了对应的配置，其余 astro 的配置大抵相同

export default defineConfig({
  // Adapter
  // https://docs.astro.build/en/guides/deploy/
  // 1. Vercel (serverless)
  // adapter: vercel(),
  // output: 'server',
  // 2. Vercel (static)
  // adapter: vercel(),
  // output: 'static',
  // 3. Local (standalone)
  adapter: node({ mode: 'standalone' }),
  output: 'server',
})

他们代表了博客的3种部署方式

Vercel (serverless)
SSR（服务端渲染）模式。
每次访问时才执行渲染，不访问就不占资源。适合部署在托管平台上。
Vercel (static)
SSG（静态渲染）模式。
所有页面在构建阶段生成，访问速度快但无法动态控制内容。
Local (standalone)
SSR（服务端渲染）模式。
会生成一个可直接运行的 Node 服务，适合自己托管。
不过是长驻进程，不像 serverless 那样按需启动。

两种 SSR 模式的主要区别在于是否支持长时间运行的任务（大多数 serverless 函数会有 10 秒左右的超时限制）。
对于文章加密这类轻量功能，两种都完全够用。

如果 standalone 模式报缺少 node 模块，安装 @astrojs/node 即可。

2. Frontmatter 增加加密字段

在每篇文章的 frontmatter 中增加 password 字段，用来存储文章的“问题与答案”：

---
title: "加密文章示例"
publishDate: "2025-11-09"
password: 
  - { question: '访问密码是什么（123456）', answer: '123456' }
  - { question: '可以设置多个问题吗（可以）', answer: '可以' }
---

在我使用的 astro-theme-pure 主题预设了博客文章的 frontmatter 字段，在 src/content.config.ts 中，其余 astro 主题大抵相同，需要自行处理

// Define blog collection
const blog = defineCollection({
  // Load Markdown and MDX files in the `src/content/blog/` directory.
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  // Required
  schema: ({ image }) =>
    z.object({
      // Required
      title: z.string().max(60),
      description: z.string().max(160),
      publishDate: z.coerce.date(),
      // Optional
      updatedDate: z.coerce.date().optional(),
      heroImage: z
        .object({
          src: image(),
          alt: z.string().optional(),
          inferSize: z.boolean().optional(),
          width: z.number().optional(),
          height: z.number().optional(),
          color: z.string().optional()
        })
        .optional(),
      tags: z.array(z.string()).default([]).transform(removeDupsAndLowerCase),
      language: z.string().optional(),
      draft: z.boolean().default(false),
      // Special fields
      comment: z.boolean().default(true),
      // 增加 password
      password: z.array(
          z.object({
            question: z.string().min(1, '问题不能为空'),
            answer: z.string().min(1, '答案不能为空')
          })
        ).default([])
    })
})

3. 调整文章渲染方式

在原先的 Astro 博客中，文章页面是在 src/pages/blog/[...id].astro 这样渲染的：

import { render, type CollectionEntry } from 'astro:content'

import { getBlogCollection, sortMDByDate } from 'astro-pure/server'
import PostLayout from '@/layouts/BlogPost.astro'

export const prerender = true

export async function getStaticPaths() {
  const posts = sortMDByDate(await getBlogCollection())
  return posts.map((post) => ({
    params: { id: post.id },
    props: { post, posts }
  }))
}

type Props = {
  post: CollectionEntry<'blog'>
  posts: CollectionEntry<'blog'>[]
}

const { post, posts } = Astro.props
const { Content, headings, remarkPluginFrontmatter } = await render(post)

这种方式属于静态生成（SSG） ：

在构建阶段（astro build），Astro 会：

执行 getStaticPaths()。
拿到所有文章（posts）并生成一个“路径列表”。
对列表中的每个路径都提前生成一个 HTML 文件（比如 /blog/xxx/index.html）。
把 post 数据写进这个静态文件里。

而我们并不想让文章内容被写入到 html 中，而是动态渲染文章内容，我们就是为此才切换到 SSR 模式，在 SSR 模式下：

你不能再用 getStaticPaths 去“预生成”页面。
Astro.props 也不会有 post、posts 这种预注入的数据（因为 SSR 时没有提前构建这些 props）。

所以我们需要调整 src/pages/blog/[...id].astro 为：

import { render, type CollectionEntry } from 'astro:content'

import { getBlogCollection, sortMDByDate } from 'astro-pure/server'
import PostLayout from '@/layouts/BlogPost.astro'

export const prerender = false

type Props = {
  post: CollectionEntry<'blog'>
  posts: CollectionEntry<'blog'>[]
}

const { id } = Astro.params
const allPosts = await getBlogCollection()
const posts = sortMDByDate(
  allPosts.filter((p) => p.collection === 'blog')
) as CollectionEntry<'blog'>[]
const post = posts.find((p) => p.id === id)
if (!post) {
  throw new Error(`Blog post not found: ${id}`)
}

const { Content, headings, remarkPluginFrontmatter } = await render(post)

4. 前端交互：Vue 组件

创建一个 Vue 小组件：

只显示问题，不知道答案
用户输入答案后提交给接口
根据接口响应刷新页面或者提示错误

这个组件可以在任何页面使用，因此不做过多描述，在你的项目中任意目录创建一个 vue 文件，之后在需要使用的 .astro 文件中通过 import 引用即可

<template>
    <div
        class="relative mb-8 pl-4 border-l-2 border-foreground/10 text-left text-sm sm:text-base text-muted-foreground leading-relaxed">
        当前文章为加密文章<br />
        请回答问题以获取查看文章的权限
    </div>
    <div class="grid gap-3.5 sm:grid-cols-1 sm:gap-4 lg:grid-cols-2 [&>*:only-child]:lg:col-span-2">
        <div class="not-prose block relative rounded-2xl border px-5 py-3 transition-all hover:border-foreground/25 hover:shadow-sm cursor-pointer"
            v-for="(item, index) in questions" :key="index">
            <div class="flex flex-col gap-y-1.5">
                <div class="flex flex-col gap-y-0.5">
                    <h2 class="text-lg font-medium">问题{{ index + 1 }}</h2>
                    <p class="text-muted-foreground">{{ item }}</p>
                </div>
                <div>
                    <input v-model="answers[index]" type="text"
                        class="flex-1 w-full rounded-lg border px-3 py-2 text-sm outline-none focus:ring-1" />
                </div>
            </div>
        </div>
    </div>
    <div class="relative w-full text-end mt-3.5">
        <button
            class="rounded-lg bg-muted px-8 py-2 text-muted-foreground text-sm hover:bg-card transition"
            :disabled="loading" @click="verifyAnswer">
            {{ loading ? '验证中...' : '验证' }}
        </button>
    </div>
</template>

<script setup lang="ts">
import { reactive, ref } from 'vue';
import { showToast } from '@/plugins/toast'

const loading = ref(false);

const props = defineProps<{
    slug: string;
    questions: string[];
}>();

const answers = reactive<string[]>(Array(props.questions.length).fill(''));

async function verifyAnswer() {
    loading.value = true
    const path = window.location.pathname
    const formData = new FormData()
    answers.forEach((a, i) => formData.append(`answer_${i}`, a))
    formData.append(`path`, path)
    const res = await fetch(`/api/verify?slug=${props.slug}`, {
        method: 'POST',
        body: formData,
        credentials: 'same-origin',
    });
    const data = await res.json()
    if (res.ok && data.success) {
        window.location.reload()
    } else {
        showToast({ message: data.error || '验证失败' })
    }
    loading.value = false
}
</script>

5. 后端接口：验证问题答案

用一个 TypeScript 文件实现验证接口：

通过 astro:content 获取文章 frontmatter。
对比用户提交的答案和正确答案。
如果验证成功，设置加密 cookie，并刷新页面显示文章内容。

import crypto from 'crypto'
import type { APIRoute } from 'astro'
import { getCollection } from 'astro:content'

const SECRET =
  process.env.COOKIE_SECRET || 'q1W2e3R4t5Y6u7I8o9P0aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789-_'

// 用 HMAC 签名
function sign(value: string) {
  return crypto.createHmac('sha256', SECRET).update(value).digest('base64url')
}

// 生成签名 cookie 值
function makeSignedCookieValue(slug: string, maxAgeSec = 86400) {
  const expires = Math.floor(Date.now() / 1000) + maxAgeSec
  const payload = `${slug}:${expires}`
  const sig = sign(payload)
  return `${payload}:${sig}`
}

// 验证签名 cookie 值
export function verifySignedCookieValue(cookieValue: string | null | undefined) {
  if (!cookieValue) return false
  const parts = cookieValue.split(':')
  if (parts.length !== 3) return false
  const [slug, expiresStr, sig] = parts
  const payload = `${slug}:${expiresStr}`
  const expectedSig = sign(payload)
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSig))) return false
  if (parseInt(expiresStr, 10) < Math.floor(Date.now() / 1000)) return false
  return slug
}

export const POST: APIRoute = async ({ request, url }) => {
  const slug = new URL(url).searchParams.get('slug')
  if (!slug)
    return new Response(JSON.stringify({ error: '非法请求' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' }
    })
  const posts = await getCollection<'blog'>('blog')
  const post = posts.find((p) => p.id === slug)
  if (!post)
    return new Response(JSON.stringify({ error: '文章不存在' }), {
      status: 404,
      headers: { 'Content-Type': 'application/json' }
    })
  const formData = await request.formData()
  const password = post.data.password || []
  const correct = password.every((p, i) => {
    const answer = formData.get(`answer_${i}`)?.toString().trim().toLowerCase()
    return answer === p.answer.trim().toLowerCase()
  })
  if (!correct) {
    return new Response(JSON.stringify({ error: '答案错误' }), {
      status: 401,
      headers: { 'Content-Type': 'application/json' }
    })
  }
  const path = formData.get(`path`)?.toString().trim()
  const cookieVal = makeSignedCookieValue(slug, 24 * 3600)
  const headers = new Headers()
  headers.append(
    'Set-Cookie',
    `verified-${slug}=${cookieVal}; Path=${path}; HttpOnly; Secure; SameSite=Lax; Max-Age=86400`
  )
  return new Response(JSON.stringify({ success: true }), {
    status: 200,
    headers: {
      'Content-Type': 'application/json',
      'Set-Cookie': `verified-${slug}=${cookieVal}; Path=${path}; HttpOnly; Secure; SameSite=Lax; Max-Age=86400`
    }
  })
}

6. 改造文章模板

在文章模板中增加逻辑：

检查文章是否加密。
检查 cookie 是否存在且有效。
如果未验证，显示 Vue 加密组件。
验证通过，显示文章内容。

在 src/layouts/BlogPost.astro 中进行调整：

---
import type { MarkdownHeading } from 'astro'
import type { CollectionEntry } from 'astro:content'

// Plugin styles
import 'katex/dist/katex.min.css'

import { MediumZoom } from 'astro-pure/advanced'
import { ArticleBottom, Hero } from 'astro-pure/components/pages'
import PageLayout from '@/layouts/ContentLayout.astro'
import { verifySignedCookieValue } from '@/pages/api/verify'
import Copyright from '@/components/custom/Copyright.astro'
import TOC from '@/components/custom/TOC.astro'
import PasswordForm from '@/components/vue/PasswordForm.vue'
import { Comment, PageInfo } from '@/components/waline'
import { integ } from '@/site-config'

interface Props {
  post: CollectionEntry<'blog'>
  posts: CollectionEntry<'blog'>[]
  headings: MarkdownHeading[]
  remarkPluginFrontmatter: Record<string, unknown>
}

const {
  post: { id, data },
  posts,
  headings,
  remarkPluginFrontmatter
} = Astro.props

const {
  description,
  heroImage,
  publishDate,
  title,
  updatedDate,
  draft: isDraft,
  comment: enableComment
} = data

const socialImage = heroImage
  ? typeof heroImage.src === 'string'
    ? heroImage.src
    : heroImage.src.src
  : '/images/social-card.png'
const articleDate = updatedDate?.toISOString() ?? publishDate.toISOString()
const primaryColor = data.heroImage?.color ?? 'hsl(var(--primary) / var(--un-text-opacity))'

// 读取 cookie 并验证
const cookieHeader = Astro.request.headers.get('cookie')
let verified = false
if (cookieHeader) {
  const cookies = Object.fromEntries(
    cookieHeader.split(';').map((s) => {
      const [k, v] = s.trim().split('=')
      return [k, v]
    })
  )
  const result = verifySignedCookieValue(cookies[`verified-${id}`])
  if (result && result === id) verified = true
}

const password = data.password || []
const questions = password.map((p) => p.question)
if (questions.length == 0) {
  verified = true
}
---

<PageLayout
  meta={{ articleDate, description, ogImage: socialImage, title }}
  highlightColor={primaryColor}
  back='/blog'
>
  {verified && !!headings.length && <TOC {headings} slot='sidebar' />}

  <Hero {data} {remarkPluginFrontmatter} slot='header'>
    <Fragment slot='description'>
      {!isDraft && enableComment && <PageInfo comment class='mt-1' />}
    </Fragment>
  </Hero>

  {verified ? <slot /> : <PasswordForm slug={id} questions={questions} client:load />}

  <Fragment slot='bottom'>
    {/* Copyright */}
    <Copyright {data} />
    {/* Article recommend */}
    <ArticleBottom collections={posts} {id} class='mt-3 sm:mt-6' />
    {/* Comment */}
    {!isDraft && enableComment && <Comment class='mt-3 sm:mt-6' />}
  </Fragment>

  <slot name='bottom-sidebar' slot='bottom-sidebar' />
</PageLayout>

{integ.mediumZoom.enable && <MediumZoom />}

总结

通过 SSR + 接口验证的方式，我们可以在 Astro 博客中实现比较安全的文章加密：

静态博客加密的核心问题在于内容已经暴露。
SSR 可以让文章内容只存在于服务端，前端无法直接获取。
前端只负责用户交互，验证逻辑和内容展示都交由服务端处理。

对于需要文章加密的博客来说，这种方式在安全性和实现复杂度之间，算是一个比较理想的平衡点。
如果你也想在自己的博客里尝试类似的加密机制，可以参考本文的思路进行改造。

如果对于文章中提到的改动仍有疑问，可以前往 GitHub 查看本次改造的提交：点我查看

Web3 去魅：写给程序员和普通人的技术解读

Wed, 05 Nov 2025 17:27:33 GMT

以为 Web3 已经没动静了，结果最近刷小红书的时候，我又碰到了那些所谓的“Web3 大师”。
你懂吧，就是那种典型的人设，大厂导师，一坐上去就开始散发“老子站在时代最前沿”的气场。

“Java ？卷！Go？已经落后了！不要聊前端了前端已经死了！后端被 AI 取代了！”

然后在平等的侮辱了所有人之后，一副老子给指条活路的态度在那里讲：“Web3 才是未来，我认识的谁谁谁，去转 Web3，现在已经在接海外的项目，一个月赚多少多少钱了，还有我之前介绍转 Web3 的谁谁谁，现在已经跳槽到什么什么地方赚了多少多少……”
完了头像点进去一看，得了，卖课的。

问题是，这种内容不仅我能刷到，我父母也会刷到。在饭桌上，父母已经开始问：“我们国家那个区块链发展的怎么样啊？是不是比不过美国啊？”、“未来不都说什么 3.0，全都用区块链，高科技啊。”
听得我一顿头大。

然而，当你真的去搜“Web3”，能找到的，要么是大多是一堆名词：区块链、智能合约、去中心化……落地的东西却少得可怜。要么是跟你讲1.0时代是只读网络，2.0时代是交互式网络，3.0时代就是去中心化，然后去宣扬网络会进入一个可读可写可拥有的时代，资产属于你个人，资本跟国家再也不能迫害你，落到实处的还是一点都没有

所以，我想写这篇文章，直接分享给父母，给他们简单讲讲 Web3 到底是个什么玩意儿，用人话解释出来，不神话、不吹嘘。

区块链 - 全世界一起记账的协议

在了解钱包和智能合约之前，先讲讲区块链本身。

区块链其实就是一套协议，就像现在互联网的协议一样，用来连接全球所有遵循这个协议的计算机。

任何一台电脑都可以加入这个协议，成为其中的一员，并共同保存协议中的所有数据。

大家一起记账的例子举烂了，我换一个例子来举例：

区块链就像一个房间，加入房间的每个人都清楚里面发生了什么。

任何人单独撒谎、篡改信息都无济于事，因为其他人都知道真实情况。

房间里的每个人越多，数据就越安全；

只有当房间里一台计算机都没有时，数据才可能消失（所以区块链的安全性依赖于节点的数量和活跃度）

它有这么几个特点：

所有信息都在同步：每台加入协议的计算机都保存一份完整的数据副本；
数据一致性靠多数共识：如果部分节点出现错误或被破坏，其他多数节点的数据会覆盖错误；
数据几乎不可能被篡改：你无法在短时间内同时改动全球大多数节点的数据，因此安全性很高；
节点关闭不怕：只要还有一台计算机在运行节点，数据就不会丢失。

当然，每台计算机作为一个节点，他也是分普通节点跟验证节点。

普通节点还分全节点跟轻节点。

不是每一个节点都是同步所有数据的全节点，那对网络还有存储要求很高。

但这不重要，只是简单说明下他概念是这么个概念

‍

钱包 - 你的数字身份证

在 Web3 世界里，你不再用“用户名 + 密码”来登录网站，而是用一个叫钱包的东西。
它就像是你在区块链上的身份证，证明“你是谁”。

之所以叫“钱包”，是因为最早的区块链主要用于转账、存币。

我的资产从“我的钱包”转到“你的钱包”。这个名字沿用下来，慢慢也代表了你在区块链世界的身份与资产。

常见的钱包软件有很多，比如 MetaMask、Rabby Wallet、Phantom、Keplr、Trust Wallet、OKX Wallet、imToken、Bitget Wallet 等。
虽然种类繁多，但它们的核心都离不开这几个关键部分：

地址（Address） ：你的公开身份，就像门牌号或身份证号，别人可以通过它找到你。
私钥（Private Key） ：你的“数字DNA”，只有你自己拥有。它能生成你的公钥和地址，用来证明“你就是你”。
签名（Signature） ：当你发起操作时，钱包会用私钥生成签名。别人可以验证这个签名确实来自你，但无法伪造。这就是区块链信任机制的基础。

‍

智能合约 - 链上的程序

在传统互联网里，我们写的程序代码通常部署在公司的服务器上，由公司来运行和维护。
而在 Web3 世界里，程序不是放在某个公司的服务器上，而是直接发布到区块链上。

这段代码就叫 智能合约（Smart Contract） 。

与其说它是一段代码，不如说它是一条“谁都改不了的规则”。

举个例子，比如你写了一个“众筹”的规则：

如果 总筹款金额 ≥ 目标金额
→ 自动把钱打给发起人
否则
→ 自动退还给所有出资者

这段逻辑一旦被上传到区块链上，就会同时被所有节点同步、验证和执行。

从此以后：

没有人能私自更改规则，因为所有节点都记录了它；
所有节点都会按照规则自动执行；
执行结果对所有人公开可查，任何人都能验证。

没有“人工审批”，也没有“后台暗箱操作”。
它就像一段永远运行的公开程序——输入条件，执行逻辑，输出结果。

换句话说，智能合约并不依赖某一台服务器，而是分布在全球的节点上共同运行。
正因为如此，它不可篡改、公开透明、自动执行，这也是 Web3 应用得以去中心化的核心基础。

费用 - 链上操作要付费

那么问题就来了：既然 Web3 不再依赖服务器，那是不是也就不需要付服务器的费用了？

其实并不是这样。
在区块链上做任何操作，都要消耗计算资源。

区块链不是慈善机构。
每一次操作（比如转账、部署合约、执行逻辑）都会被所有节点同步和验证。
而这些节点背后是真实的计算机，它们需要电力、带宽和硬件支持。
因此，系统规定：

谁使用计算资源，谁就需要支付费用。

这个费用就叫 Gas Fee（燃料费） 。

操作越复杂，消耗的 Gas 越多。
这也是为什么链上不适合直接存放大文件或频繁操作的原因。

举个例子，如果我希望一个大文件不被篡改，
我不需要把整个文件上传到区块链上。
我只需要把文件的哈希值（Hash） 存到链上，之后任何人只要重新计算文件的哈希并与链上记录比对，
就能确认文件是否被改动。

这样既节省 Gas，又能保持数据的可信性与可验证性。

节点是谁提供的

节点其实就是在跑区块链软件的电脑，可以是：

个人开发者在家里的电脑
矿工或验证者的服务器
机构公司搭建的节点
提供节点服务的公司（比如 Infura、Alchemy），让你不用自己跑节点也能和链交互

去中心化的核心就是节点分布广泛，不存在某个地方关闭就能毁掉整个链的情况。只要还有节点在，链就能继续运行。

早期的挖矿就是围绕这个机制展开的：区块链中，每一秒都有各种事情发生：有人转账，有人操作合约，有人执行程序。如果每一秒的所有事情都让每台电脑实时记下来，信息量会太大，根本保存不过来。

于是区块链有个规则：每隔一段时间，比如两分钟，把过去两分钟里发生的事情整理成一个“时间归档”，然后同步给全世界的节点。大家都保存一份副本，就像把过去的时间切成一段段的小片段，既保证了数据完整，也不会让整个链庞大到无法管理。

但是，谁来做这份归档呢？全世界的节点都可以参与竞争。系统会发布一道非常难的数学题，节点们用自己的算力去解，谁先解出来，谁就有权利把这一段时间的事情整理好，并广播给所有人。成功的节点就能得到奖励，包括系统发的区块链币和这一段时间所有操作支付的 Gas。

算力越强的节点，越有机会赢得这场“时间归档赛”。所以早些年，大家都疯狂投入算力去挖矿，本质上就是用自己的能力去竞争记录过去的时间片段，同时获得奖励。

当然因为这种方式太耗电，把很多人卷进了一场无限战争，因此后来也出现了很多新的机制，比如靠抵押资金或者信誉度来证明自己有资格而不纯粹靠算力。

但不论如何这个模式吸引了很多人，让其有动力成为区块链的节点，变相保证了整个区块链几乎不可能被摧毁，因为不管全球哪个犄角旮旯只要还有一个节点整个区块链就依然存在

Web3 的局限和现实

虽然 Web3 技术看起来很吸引人，但现实中还是面临不少问题：

链上操作慢，费用高；
用户体验差：丢了私钥就意味着钱包没了，交易得等矿工确认；
完全去中心化仍然是理想，很多 DApp 仍然依赖中心化的前端或者缓存；
大部分 Web3 应用仍然处于实验阶段，炒作和投机现象严重。

区块链因为按时间段归档的特性，本身就不具备严格的实时性。每笔操作都得等到下一个区块确认，才能被全网认可。

区块链追求的核心是数据的透明性、可靠性和不可篡改性，而不是瞬时同步。换句话说，Web3 很难像传统互联网那样，支持毫秒级的实时交互。

同时，因为每次操作都要支付 Gas 费用，数据上链的成本也挺高，所以下链的东西也不能随便放进去。

再说说私钥管理的问题，这其实是 Web3 设计里的一个理想化部分。在传统的中心化模式下，用户面对的是一个有责任的主体。就像我们用化妆品，如果出了问题，我们不需要追究每个成分来源，只要找化妆品公司负责；如果不行，往上找政府管。

但在去中心化的世界里，这个“责任主体”就没了。很多人可能觉得这就意味着自由，但随之而来的却是保障的消失。没人会为你的损失负责。

比如我把钱放在支付宝，数据是中心化的，支付宝说了算。如果我的手机丢了或者忘了密码，我可以去找支付宝，他们能帮我找回我的钱。
但如果我的钱在区块链上，确实去中心化了，但如果我丢了私钥，那就真的没救了。别人偷不走的钱，我们自己也拿不回来。

这并不意味着 Web3 毫无意义。它依然有它的市场和价值，只是目前在我们现有的社会体制下，它的发展空间是有限的。十多年来，Web3 的发展仍然没能摆脱“炒币”的刻板印象，吸引了大量投机者，但至今没有出现像抖音、淘宝这样真正的大众应用。

总结

Web3 并不是魔法，也不是币圈炒作的工具。它的核心逻辑是：

你写的代码和数据，不存在某台服务器，而是分布在全网节点，每个节点都帮你保存和验证。

去中心化的本质是 全网节点共同维护数据和程序，不依赖某个公司或者服务器。

他不是新大陆，而是给互联网装了身份证和数字钱包，把程序和数据交给全网节点一起保存验证。

理解这个逻辑，比盲目追风口或者听直播吹牛更有价值。

收藏版：Phinx 数据库迁移完全指南

Tue, 28 Oct 2025 10:30:12 GMT

最近在维护老项目时，又一次用到了 Phinx。这个工具我已经用了很多年，几乎每个项目都会用上它。它属于那种平时不常用，但每个项目都离不开 的工具。

问题在于，它用得不频繁，每次写迁移脚本时总会忘记某个参数怎么写、某个字段该用什么类型。这些当然可以去查官方文档，但 Phinx 的文档虽然内容齐全，却总让我觉得信息分散、查起来不够顺手。

于是，我干脆花点时间，把自己常用的命令、配置方式、字段类型和参数说明都系统地整理了一遍。一方面方便自己查阅，另一方面也希望能帮到同样在项目中使用 Phinx 的开发者。

如果你也在 PHP 项目里用 Phinx 管理数据库迁移，这篇文章或许能成为你的「快捷参考手册」。

前期配置

安装 Phinx

composer require robmorgan/phinx

初始化配置

执行初始化命令：

vendor/bin/phinx init

该命令会在项目根目录下生成一个 phinx.php 配置文件。
配置文件中：

paths 用于指定迁移脚本与填充脚本的路径；
environments 用于定义不同环境（例如开发、测试、生产）的数据库配置；
若执行迁移命令时不指定环境，则默认使用 default_environment 指定的环境。

环境配置与 .env 支持

为了统一管理数据库配置，我习惯用 .env 文件来维护连接信息。
但由于 phinx 脚本并不运行在 PHP 框架生命周期内，常见的 .env 加载方式（如 Laravel 的）无法直接使用，因此我通常会额外安装 vlucas/phpdotenv：

composer require vlucas/phpdotenv

然后在 phinx.php 中添加如下配置：

<?php
$dotenv = Dotenv\Dotenv::createImmutable(__DIR__);
$dotenv->load();
return [
    "paths" => [
        "migrations" => "database/migrations",
        "seeds" => "database/seeds"
    ],
    "environments" => [
        "default_migration_table" => "phinxlog",
        "default_environment" => "production",
        "production" => [
            "adapter" => "mysql",
            "host" => $_SERVER['DB_HOST'],
            "name" => $_SERVER['DB_NAME'],
            "user" => $_SERVER['DB_USER'],
            "pass" => $_SERVER['DB_PASS'],
            "port" => $_SERVER['DB_PORT'],
            "charset" => $_SERVER['DB_CHARSET']
        ]
    ]
];

常用命令

创建迁移文件

vendor/bin/phinx create 迁移名称

Phinx 会自动根据时间戳与名称生成迁移文件。
命名建议保持统一规范：

创建表：Create + 表名 → 例如 CreateUsersTable
修改表：Modify + 表名 + 操作 → 例如 ModifyUsersAddStatus
删除表：Delete + 表名 → 例如 DeleteOldLogsTable

Phinx 会自动将大驼峰命名转为蛇形文件名，例如 CreateUsersTable → 20251028123045_create_users_table.php

执行迁移

没什么好说的，执行这个命令即可执行迁移

vendor/bin/phinx migrate

参数说明：

-e：指定环境（默认 production）
-t：指定执行到的版本号（不传则执行到最新）
--dry-run：仅打印 SQL 而不实际执行

注意：-t 不是只执行单个版本，而是顺序执行直到目标版本号为止。

设置断点（Breakpoint）

生产环境中执行迁移后，建议立刻设置断点。
断点能防止误操作导致大规模回滚。

vendor/bin/phinx breakpoint

参数：

-e 环境名
-t 版本号
-r 删除断点

回滚迁移

慎用！
迁移的回滚会撤销数据库结构更改，例如删除表或字段，表中数据会全部丢失。
生产环境不建议直接回滚，而是通过新的迁移来完成结构恢复。

vendor/bin/phinx rollback

参数说明：

-e 环境名
-t 指定版本号（或 0 回滚全部）
-d 按日期回滚（YYYYmmddHHiiss）
-f 强制回滚（忽略断点）
--dry-run 仅打印 SQL 不执行

查看状态

用于查看迁移执行状态，确认哪些迁移尚未执行。

vendor/bin/phinx status

参数说明：

-e：环境名

创建填充（Seeder）

vendor/bin/phinx seed:create 填充名称

命名建议使用表名 + 填充描述，例如：

UsersAddDemoDataSeeder

执行填充：

vendor/bin/phinx seed:run

参数：

-e 指定环境
-s 指定执行的 Seeder，可多次传入

迁移脚本详解

支持的字段类型

Phinx 在 MySQL 下支持的字段类型如下：

| 类型 | ---------------- | smallinteger | integer | biginteger | float | double | decimal | bit | boolean | char | string | text | enum | set | uuid | date | time | datetime | timestamp | binary | blob | tinyblob | mediumblob | longblob | json | MySQL 类型 | 必需参数 | 说明 | | ------------ | --------------------- | ------------------ | | SMALLINT | — | 小整数 | | INT | — | 常规整数 | | BIGINT | — | 大整数 | | FLOAT | — | 单精度浮点数 | | DOUBLE | — | 双精度浮点数 | | DECIMAL(M,D) | precision,scale | 定点小数（金额等） | | BIT | — | 位字段 | | TINYINT(1) | — | 布尔值（0/1） | | CHAR(n) | limit | 定长字符串 | | VARCHAR(n) | limit | 可变长度字符串 | | TEXT | — | 文本 | | ENUM(...) | values | 枚举类型 | | SET(...) | values | 集合类型 | | CHAR(36) | — | UUID字符串 | | DATE | — | 日期 | | TIME | — | 时间 | | DATETIME | — | 日期与时间 | | TIMESTAMP | — | 时间戳 | | BINARY(n) | limit | 定长二进制数据 | | BLOB | — | 二进制大对象 | | TINYBLOB | — | 小型二进制 | | MEDIUMBLOB | — | 中型二进制 | | LONGBLOB | — | 超大二进制 | | JSON | — | JSON 数据类型 |

常用字段参数

| 参数名 | 类型 | 说明 | | ------------------ | ------------ | --------------------------------------------------------------- | | limit / length | int | 长度或字节限制 | | default | mixed | 默认值 | | null | bool | 是否允许为 NULL | | after | string | 放置在某个字段之后（或 \Phinx\Db\Adapter\MysqlAdapter::FIRST ） | | comment | string | 字段注释 | | precision | int | 小数总位数 | | scale | int | 小数位数 | | signed | bool | 是否允许负数 | | values | array/string | 枚举或集合可选值，英文逗号隔开的字符串或数组 | | identity | bool | 是否自增（需搭配 null:false） |

各种操作调用代码

如果对表格形式不感兴趣，可以直接通过以下完整迁移脚本理解字段定义方式。

<?php

declare(strict_types=1);

use Phinx\Db\Adapter\MysqlAdapter;
use Phinx\Migration\AbstractMigration;

final class CreateTable extends AbstractMigration
{
    /**
     * Change Method.
     *
     * Write your reversible migrations using this method.
     *
     * More information on writing migrations is available here:
     * https://book.cakephp.org/phinx/0/en/migrations.html#the-change-method
     *
     * Remember to call "create()" or "update()" and NOT "save()" when working
     * with the Table class.
     */
    public function change(): void
    {
        // 前置说明：
        // create() 操作: 表不存在的情况下，创建表，并保存字段操作
        // update() 操作: 表存在的情况下，变更表，并保存字段操作
        // 所有的操作记得到最后一定需要对构建的表对象执行保存操作，否则不会执行

        // 判断表是否存在: $this->hasTable('table_name');

        // 删除表: $this->table('table_name')->drop()->save();

        // 构建表
        $table = $this->table('table_name', ['id' => 'table_id', 'comment' => '这是 table 表']);
        // 第二个参数字段，可不传，主要用于在 create() 时构建表级的基本信息
        // 支持的参数：
        // id:            主键 ID 列，传入字符串或者布尔类型
        //                    如果是字符串：按照字符串内容创建自增主键
        //                    如果是false：不自动创建主建
        //                    如果不传：自动创建名称为 id 的自增主键
        // comment:       设置表的注释
        // row_format:    设置表的行格式（MySQL 特有，例如 DYNAMIC, COMPACT, REDUNDANT, COMPRESSED）
        // engine:        设置表的存储引擎（MySQL 特有，例如 InnoDB, MyISAM, MEMORY）
        // collation:     设置字符集的排序规则，默认 utf8mb4_unicode_ci
        // signed:        整数类型是否允许负数，默认 false
        // limit:         设置主键最大长度

        // 变更表注释
        $table->changeComment('这是 table 表新的注释');
        // 更改主键，可以设置多个列组联合主键
        $table->changePrimaryKey(['new_id']);
        // 重命名表
        $table->rename('new_table_name');

        // 检查字段是否存在：$table->hasColumn('username');

        // 重命名字段
        $table->renameColumn('老字段名', '新字段名');

        // 删除字段
        $table->removeColumn('字段名');

        // 添加字段
        $table->addColumn('字段名', '类型', ['参数'])
              ->addColumn('avatar', 'string', ['comment' => '头像', 'null' => true, 'after' => 'name'])
              ->addColumn('created_at', 'integer', ['comment' => '创建时间', 'null' => false, 'limit' => MysqlAdapter::INT_BIG]);
        // 类型：
        // 很多不必要或可以简化定义的类型，例如数字方面，可以全部都设置为 `integer` 通过 `limit` 参数设置长度即可自动创建对应类型
        // 以下是支持的类型：
        // smallinteger(SMALLINT):  小整数
        // integer(INT):            常规整数
        // biginteger(BIGINT):      大整数
        // float(FLOAT):            单精度浮点数
        // double(DOUBLE):          双精度浮点数
        // decimal(DECIMAL(M,D)):   定点小数，必须携带 `precision` 与 `scale` 参数
        // bit(BIT):                位字段
        // boolean(TINYINT(1)):     布尔值（0/1）

        // char(CHAR(n)):           定长字符串，必须携带 `limit` 参数
        // string(VARCHAR(n)):      可变长度字符串，必须携带 `limit` 参数
        // text(TEXT):              文本
        // enum(ENUM(...)):         枚举类型，必须携带 `values` 参数
        // set(SET(...)):           集合类型，必须携带 `values` 参数
        // uuid(CHAR(36)):          UUID字符串

        // date(DATE):              日期（YYYY-MM-DD）
        // time(TIME):              时间（HH:MM:SS）
        // datetime(DATETIME):      日期与时间
        // timestamp(TIMESTAMP):    时间戳

        // binary(BINARY(n)):       定长二进制数据，必须携带 `limit` 参数
        // blob(BLOB):              二进制大对象
        // tinyblob(TINYBLOB):      小型二进制
        // mediumblob(MEDIUMBLOB):  中型二进制
        // longblob(LONGBLOB):      超大二进制
        // json(JSON):JSON          数据类型

        // 参数：
        // 以下是支持的参数：
        // limit / length:          长度，int 类型，内容跟随字段类型变化
        // default:                 默认值，类型根据字段类型变化
        // null:                    是否允许为 null，bool 类型，true 或者 false
        // after:                   指定字段应该放在哪个列之后，string 类型传递列名，或者 \Phinx\Db\Adapter\MysqlAdapter::FIRST
        // comment:                 字段注释，string 类型
        // precision:               结合 scale 设置小数精度，int 类型
        // scale:                   结合 precision 设置小数精度，int 类型
        // signed:                  是否允许负数，bool 类型
        // values:                  枚举类型，可以是英文逗号分隔的string，或array
        // identity:                数字类型自增长，bool类型，需要设置 null:false

        // 修改字段
        $table->changeColumn('字段名', '类型', ['参数']);

        // 设置索引
        $table->addIndex(['字段名']);

        // 删除索引
        $table->removeIndex(['字段名']);
        // 或者
        $table->removeIndexByName('索引名');
    }
}

填充脚本（Seeder）示例

<?php

declare(strict_types=1);

use Phinx\Seed\AbstractSeed;

class TableAddDemoDataSeeder extends AbstractSeed
{
    /**
     * Run Method.
     *
     * Write your database seeder using this method.
     *
     * More information on writing seeders is available here:
     * https://book.cakephp.org/phinx/0/en/seeding.html
     */
    public function run(): void
    {
        // 构建数据
        $data = [
            [
                'body'    => 'foo',
                'created' => date('Y-m-d H:i:s'),
            ],
            [
                'body'    => 'bar',
                'created' => date('Y-m-d H:i:s'),
            ]
        ];
        // 构建表
        $table = $this->table('table_name');

        // 添加数据，并保存
        $table->insert($data)
              ->saveData();

        // 清空表中的所有数据
        $table->truncate();
    }
}

老项目迁移接入

如果你是从已有数据库切换到 Phinx，可使用 phinx-migrations-generator 自动生成迁移文件。

composer require odan/phinx-migrations-generator --dev

它会直接读取现有的 phinx.php 配置，无需额外设置。
执行以下命令即可生成当前数据库结构的迁移文件：

vendor/bin/phinx-migrations generate

最后

Phinx 是一个非常轻量却强大的迁移工具，适用于几乎所有独立 PHP 项目。
写这篇笔记的初衷很简单——自己每次都要重新翻文档太麻烦了，不如干脆整理一份系统化的版本。
如果你也有相同的困扰，希望这篇文章能让你变得方便一些觉得有用的话，别忘了收藏这篇文章～更多内容可以在我的网站 https://hejunjie.life 查看

想让默认头像不再千篇一律，就顺手复刻了一下 GitHub 的思路

Mon, 27 Oct 2025 15:48:46 GMT

在各种平台上，初始注册的用户通常都会被分配一个默认头像。
但如果你的平台有互动功能，比如评论、留言、排行榜，一堆一模一样的默认头像排在一起就会显得很单调，甚至有些奇怪。

当然，你也可以让用户自己去换头像，但现实是：大多数人根本懒得去换。

于是我就想：能不能让默认头像也“有点个性”呢？
然后我想到了 GitHub。

起因

GitHub 的默认头像其实挺有意思的。
每个新用户的头像看起来都不一样，但又有明显的统一风格。
一眼就能认出这是 GitHub 的头像，却几乎不会出现重复。

出于好奇，我开始想：

他们到底是怎么做到的？
是根据用户名生成的吗？
还是用某种随机算法？

于是，我顺手研究了一下 GitHub 默认头像的生成逻辑。

复刻的过程

GitHub 的默认头像基本原理是：根据用户的唯一标识生成一张方块头像，同时随机但可控地分配颜色和图案。

这种方式有几个显著优势：

视觉上丰富：每个头像都不同，但风格统一
生成速度快：不需要上传和存储文件
用户感知独一无二：即使是默认头像，也有个人特色

我用 Go 写了一个小项目，实现了类似的功能，并发布在 GitHub 上：点击查看。

它的特点是：

只需传入一个字符串（如用户名），就能生成头像
颜色、方块分布、比例尽量还原 GitHub 风格
每个输入都会生成一个独一无二的头像

技术小细节

简单说一下实现原理：

首先把输入的字符串（比如用户名）做 Hash，得到一个固定长度的数字序列。
然后用这个数字序列去生成颜色和方块分布：同样的输入总会得到同样的数字，所以生成的头像也总是一致；不同的输入则会产生不同的数字，自然生成不同的头像。
具体来说，可以用这些数字去随机生成 RGB 颜色值，同时计算方块的排列方式，从而得到多样化、独一无二的方块头像。

这种方法既保证了风格统一，又能让每个头像看起来不同，效率也很高，不需要存储图片。

效果展示

你可以直接试试这个在线效果：点击查看。

输入任意字符串，它就会返回一个专属头像：

同样的输入，总是生成相同的图案
不同的输入，总会得到不同的组合

这就像一个小型的“盲盒”，每次输入都能看到不一样的惊喜。

未来可能的扩展

这个思路其实很有拓展空间。
比如，我想过以后可以像芭比娃娃那样，准备很多简笔风格的人脸元素——头发、眼睛、饰品（比如眼镜）等——然后通过同样的随机方式组合它们，还能随机分配颜色。

这样一来，每个默认头像不仅是抽象的方块图案，还可以变成可爱的人物头像，依然保持“同样的输入生成同样头像，不同输入生成不同头像”的特性。
未来有时间的话，可能会尝试实现这个版本，给头像多一点“可玩性”。

小结

这个项目虽然小，但做起来意外地有趣。

它让我意识到，有些东西看起来没什么“实用价值”，却能给用户带来小小的乐趣。
或许它不会改变世界，但至少能让页面多一点变化，也让我在折腾过程中学到不少东西。

如果你也想让你的平台默认头像不再千篇一律，不妨试试这个方法，也许能给用户带来一点“专属感”。

在 Astro 博客中优雅使用 51.la 统计数据

Fri, 24 Oct 2025 19:44:10 GMT

作为老牌网站流量统计服务商，51.la 提供每月高达 1000 万次的免费统计额度，非常适合个人博客或小型网站使用。不过，51.la 默认的统计展示是通过嵌入 JS 文件自动渲染的，这种展示方式对美观性和自定义性有限，对于追求页面整洁或者想要自己设计展示风格的博主来说不太方便。

我之所以想自己处理 51.la 的统计，是因为我希望更直观地看到有多少人访问我的博客，了解访客的访问情况，从而改进内容和布局。经过尝试，我找到了一个方法：解析 51.la 的 widget JS 数据，自行在 Astro 中渲染统计数据，既保留统计功能，又可以完全控制展示效果。下面分享我的完整经验。

配置文件管理

在 Astro 中，一般会有一个全局配置文件，用来集中管理各种配置。我们可以把 51.la 的相关信息放在一起，示例：

export const metrics: { enable: boolean; sdk: string; id: string; ck: string; widget: string } = {
  // 51.la 统计开关
  enable: true,
  // 统计网站的配置信息，在后台获取
  // See: https://v6.51.la/report/setup/params/statistics
  sdk: 'https://sdk.51.la/js-sdk-pro.min.js',
  id: 'xxxxxxxxxxxxxxxx',
  ck: 'xxxxxxxxxxxxxxxx',
  // 数据挂件 javascript 地址
  // See: https://v6-widget.51.la/v6/xxxxxxxxxxxxxxxx/quote.js
  widget: 'https://v6-widget.51.la/v6/xxxxxxxxxxxxxxxx/quote.js'
}

如果你的项目中没有配置文件，可以在 src 下创建一个 TS 文件，然后在 tsconfig.json 的 paths 中添加，例如：

"@/site-config": ["src/site.config.ts"]

这样，在 Astro 页面中就可以直接引入：

---
import { metrics } from '@/site-config'
---

集中管理配置的好处是，一旦需要修改统计信息，只需改一处即可，方便维护。

在入口加载统计

为了统计用户访问情况，我们需要在页面入口加载 51.la 的 SDK。不同主题的入口文件可能不同，Astro 默认的入口是 src/layouts/Layout.astro。如果不确定，可以从 pages/index.astro 开始反推去找包含完整 HTML 结构的布局文件。在布局文件的 <head> 中加入：

{metrics.enable && <script is:inline src={metrics.sdk} />}
<script is:inline type='module' data-astro-rerun define:vars={{ metrics: metrics }}>
  if (metrics.enable) {
    LA.init({ id: metrics.id, ck: metrics.ck })
  }
</script>

注意：对应的文件顶部需要引入配置：import { metrics } from '@/site-config'

这样，每次用户访问页面时都会触发 51.la 的统计，后台就能记录访客数据。

创建数据展示组件

为了美观，我们可以自己在 components 里创建一个组件（例如 Metrics.astro）来展示数据，这样就不依赖 51.la 默认的 JS 渲染。示例：

---
import { metrics } from '@/site-config'
---

<div id='widget'>
  加载中...
</div>

<script is:inline type='module' data-astro-rerun define:vars={{ metrics: metrics }}>
  if (metrics.enable && metrics.widget) {
    fetch(metrics.widget)
      .then((res) => res.text())
      .then((data) => {
        let num = data.match(/(<\/span><span>).*?(\/span><\/p>)/g)
        if (!num) {
          console.warn('51.la 数据匹配失败')
          return
        }
        num = num.map((el) => el.replace(/(<\/span><span>|<\/span><\/p>)/g, ''))
        const titles = [
          '最近活跃',
          '今日人数',
          '今日访问',
          '昨日人数',
          '昨日访问',
          '本月访问',
          '总访问量'
        ]
        const container = document.getElementById('widget')
        let html = ''
        for (let i = 0; i < num.length; i++) {
          html += `<div>标题：${titles[i]}</div>`
          html += `<div>内容：${num[i]}</div>`
        }
        container.innerHTML = html
      })
      .catch((err) => {
        console.error('51.la 数据获取失败:', err)
        document.getElementById('widget').innerHTML = '加载失败'
      })
  }
</script>

样式可以根据自己的需求进行美化，例如网格布局、卡片样式等。这里的重点是把数据准确展示出来，让访客统计信息可视化。

之后，将你的组件在你想要展示的页面中尽性应用即可，就像其他的组件一样

总结

通过这种方式，你可以：

保留 51.la 的统计功能，无需自己搭建后端统计系统。
自定义统计数据显示方式，让数据展示更美观、更符合博客风格。
在 Astro 项目中简单集成，配置和组件化管理清晰。

我之所以选择自己解析 widget 数据，是希望在博客上直观看到访客情况，了解每天有多少人访问、哪些内容更受欢迎。这样可以更有针对性地优化博客内容，同时也享受了 51.la 提供的免费统计额度。

注意：如果 51.la 的 widget JS 结构有改动，正则匹配可能需要更新。但在目前版本下，这种方法非常稳妥。

这样，你就可以既“白嫖” 51.la 免费流量统计，又能自由控制数据展示效果，同时清楚了解自己的博客访问情况。

用自己的服务器做一个「临时网络代理」：记录一下开发阶段的一个小技巧

Mon, 20 Oct 2025 15:54:39 GMT

⚠️ 本文不涉及任何“科学上网”内容，仅用于记录我在服务器开发过程中遇到的依赖下载问题。
之前网安的朋友都专门打电话提醒过我，我也不敢乱写。
这里讲的只是一个开发场景下的代理转发技巧，仅涉及客户端问题，不涉及任何服务端内容。

背景：有些烦人的客户

很多时候，我们的服务器环境要下载外部依赖：

PHP 用 Composer 拉包
Node.js 要 npm
Python 要 pip
Go 要 go get
甚至 Git clone GitHub

理论上，我们都可以找国内代理源，比如：

Composer 的中国镜像
npm 的淘宝镜像
pip 的清华源

不过，国内代理源的状况暂且不论——万一挂了，还得去找别的方案。

问题是，有时候你会遇到这种客户：

“你做的时候给我录个屏，每一步怎么做的我也学一下”
“你这个东西怎么搞好的，跟我讲一下，下次我自己来”

然后等你把他教会了之后，他居然又来一句：

“原来这么就好了，我看你们技术也没多难，我自己搞搞看也挺行哈”

😑😑😑

这一不是我的项目，我只是帮忙解决基础问题。
二来我也没收费，一顿教完没个感谢就算了，还贬低人。

平时有人找我问东西，我还是愿意尽力帮忙，毕竟 解决问题 = 经验积累。
我不讨厌经验积累，顺手帮忙也算交个朋友。

但有时候遇上完全不懂技术、又不尊重别人工作价值的情况……
我就干脆不折腾那些国内代理源了。

遇到环境问题，我就直接让服务器连我自己的服务器做代理：
我这边配置好、调整完，把问题解决掉，然后断掉代理。

大家要是愿意聊天、问问题，我就教；
碰到那种不尊重人的客户，教了也没意义，反而亏了自己的时间。

方案概览

我自己用来工作的服务器（工作机）网络通畅，于是我在上面开了一个小小的服务端。

需要处理环境问题的服务器（开发机）作为客户端连接它，从而获得一个「临时代理隧道」。

整个过程：

开发机 → 工作机 → 外部依赖源（GitHub、Composer、npm 等）

我只需要保持一次新的连通即可。

工作机配置

安装客户端（以 Ubuntu 为例）：

apt install shadowsocks-libev -y

编辑 /etc/shadowsocks-libev/config.json：

{
    "server": "0.0.0.0",
    "server_port": 8399,
    "password": "临时密码",
    "timeout": 300,
    "method": "chacha20-ietf-poly1305",
    "mode": "tcp_and_udp"
}

启动服务：

systemctl enable shadowsocks-libev
systemctl start shadowsocks-libev

到这里工作机就完成了，防火墙记得打开设置好的端口号（比如上面配置里面的8399）

让开发机临时使用这个代理

开发机跟工作机的前期步骤相同

安装客户端（以 Ubuntu 为例）：

apt install shadowsocks-libev -y

编辑 /etc/shadowsocks-libev/config.json：

{
    "server": "工作机IP",
    "server_port": 8399,
    "local_address": "127.0.0.1",
    "local_port": 1080,
    "password": "临时密码",
    "timeout": 300,
    "method": "chacha20-ietf-poly1305",
    "mode": "tcp_and_udp"
}

启动服务：

systemctl enable shadowsocks-libev-local@config
systemctl start shadowsocks-libev-local@config

之后本地 1080 端口的网络请求就会通过开发机来执行，流程如下：开发机 (127.0.0.1:1080) → 工作机 (8399) → 网络

Git

Git 有自己的代理配置：

git config --global http.proxy socks5h://127.0.0.1:1080
git config --global https.proxy socks5h://127.0.0.1:1080

Shell / 命令行工具

如果你想让 pip、go get、composer 等命令行工具都走这个代理，可以给当前开发机 shell 设置环境变量：

export https_proxy=socks5h://127.0.0.1:1080
export http_proxy=socks5h://127.0.0.1:1080
export all_proxy=socks5h://127.0.0.1:1080

命令执行完后，删除临时设置即可恢复正常网络：

unset all_proxy http_proxy https_proxy

如果再也不打算上这台代理服务器，也可以直接删除客户端配置，或者我这边直接改掉在服务端的密码即可。

总结

这套方案可以：

快速帮客户解决依赖下载问题
不用折腾国内代理源
保留自己对操作环境的控制，避免被“白嫖”

一句话概括就是：

用完即走，帮你搞定，不教你翻车。

从 Hexo 到 Astro：重构我的个人博客

Fri, 17 Oct 2025 12:29:33 GMT

写博客这件事，老实说，现在可能不太流行了，流量也未必多，但对我来说，有没有博客是两回事。

过去几年，我一直用 Hexo 搭建和维护我的博客，主题丰富、社区活跃，用得也很开心。

老博客：

不过，随着我对博客的需求越来越多，我发现 Hexo 在一些定制化操作上有些局限。于是，我决定尝试用 Astro 来重构我的博客。

新博客：

关于博客这件事

我其实并不指望有人会主动来看我的博客。现在这个时代，社交平台的信息流太快，主动搜索和阅读博客的人越来越少，自然流量几乎可以忽略不计。
但我觉得，有没有人看是一回事，写不写又是另一回事。

写东西是好的。
无论是记录生活、整理思路，还是在完成一个项目后做个总结强化记忆，这个过程本身就是一种复盘和沉淀。哪怕只是写在记事本里，都有意义。而当我把这些内容放到自己的博客上，它又变成了另一种存在——像是一张我在网络上的个人名片。

没有这张“名片”，当然也没什么关系；但有这么一个地方，能承载我的想法、积累和小尝试，我会觉得挺开心的。

为什么想要重构

虽然 Hexo 写博客简单、方便，但有时候我想在页面上增加一些小定制功能或展示自己的项目。Hexo 在这方面略显死板，很难灵活调整。

我希望能实现几个目标：

可以继续用 Markdown 写博客，不增加复杂度
页面可以随意增加一些互动组件或者项目展示
当有小想法时，可以直接用 React/Vue 去实现

总之，我希望博客不仅仅是写文章的地方，还能承载一些创意和技术实践。

Astro 的优势

选择 Astro 的主要原因是它的灵活性：

框架自由：可以在同一个页面混合使用 React、Vue、Svelte 等组件
性能优秀：默认静态生成，访问速度快
开发自由度高：博客可以作为博客，也可以展示项目或其他创意

Astro 给了我一个既能保持写作效率，又能随意定制页面的空间，这正是我想要的。

使用体验与感受

重构后的博客体验让我很满意：

平常写博客依旧简单，Markdown 就够了
想改动或加入小功能时，可以直接用组件实现
博客不只是博客，也能展示项目、作品或其他想法

虽然我明白现在大家可能已经不太关注博客，也可能没人看，但对我来说，有一个可以自由调整和实践的平台，这种感觉非常爽。

总结

总的来说，从 Hexo 到 Astro 是一次让我非常满意的重构，更像是一次“重塑表达方式”的过程。

它让我能在继续写字的同时，也能把我的代码、项目和想法融在一起。这种感觉挺好。

如果你对博客有定制化需求，或者想尝试更多前端技术，我可以说 Astro 是一个值得尝试的选择。

不过如果你真的对代码没兴趣，也不想去定制什么东西，只是用来写文章放文章的话，那可能 Hexo 还是会方便一些

如果你也想了解 Astro 的使用体验，可以来看看 :)

地址：hejunjie.life

一个小项目的记录：PHP 分账组件

Mon, 13 Oct 2025 11:32:38 GMT

最近整理了一个自己做的小项目——PHP Trade Splitter ，是一个交易/利润分账组件。今天想分享一下，也算是记录自己的小成果，也顺便展示一下技术思路。

为什么会做这个包

说白了，就是因为工作/项目里老是碰到分账逻辑：

平台抽成
作者收益
代理或渠道分润
阶梯奖励
多级递归计算

以前都是直接写死在业务里，每次改需求都得重构，越改越心累。

于是我想：干脆抽象出来，做一个通用组件，能够：

快速调用，一行代码搞定分账
可扩展，能注册自定义策略
覆盖大多数常见分账规则

顺便用它自己解决问题，也方便别人参考。

架构思路：策略模式解耦

核心思想其实挺简单：策略模式。

Splitter：统一入口，负责分账调度
StrategyInterface：所有分账规则都实现它
SplitContext：封装分账上下文（总额、参与者）
Allocation：分账结果对象，支持 toArray() 输出

好处就是，如果以后出现新规则，直接写个策略类注册进去就行，不用动核心逻辑。

概念上可以想象成这样：

├─ Splitter.php                # 统一入口，负责分账调度
├─ Contracts/
│  └── StrategyInterface.php   # 所有分账规则都实现它
├─ Models/
│  ├── Allocation.php          # 分账结果对象，支持 `toArray()` 输出
│  └── SplitContext.php        # 封装分账上下文（总额、参与者）
└─ Strategies/                 # 内置策略类（Percentage, Fixed, Ladder, Recursive）

内置策略概览

组件内置了四种策略，覆盖绝大多数场景：

百分比分账（Percentage）

按比例分配金额。例如 10% 给平台，90% 给作者。适合固定比例抽成场景。

固定金额分账（Fixed）

直接指定每个人的金额。总和不能超过总额。适合代理固定提成或奖励金额场景。

阶梯分账（Ladder）

根据金额区间设置不同分成比例，适合阶梯奖励或多级代理。比如收入低于 1k 用 5%，收入 1k~5k 用 10%，超过 5k 用 15%。

递归分账（Recursive）

适合多级渠道分润，每层收益基于上一层金额计算，然后得到净收益。避免嵌套循环写复杂逻辑，非常清晰。

如果你想看具体代码示例，我在仓库里提供了 demo：tests/demo.php

自定义策略

除了内置策略，你也可以写自己的策略类，只要实现接口就可以注册。比如你想写一个“全部给某个人”的策略：

概念上就是实现一个接口，然后返回总额给指定对象，调用方式和内置策略一致。

使用体验

一行代码即可完成分账
分账结果可以直接转换为数组或 JSON，方便存储或返回
异常情况和边界条件都有处理，比如比例不合法、总额超出等

分享感想

其实这个包本身逻辑不复杂，但价值在于解决重复痛点：

遇到分账问题不用每次重写逻辑
可维护性提升
自己和别人都能快速上手

所以即便是小组件，也可以体现技术思路和设计能力。

总结

这是一个 轻量、灵活、可扩展的 PHP 分账组件
核心就是 策略模式 + 可注册自定义策略
分享出来，也是记录自己技术历程，同时方便别人参考

如果你也碰到分账痛点，或者想看看策略模式在小项目里的应用，可以去看看

再也不用翻一堆日志！一键部署轻量级错误监控系统，帮你统一管理 PHP 报错

Fri, 10 Oct 2025 00:16:07 GMT

维护多个项目的人，大概都明白那种感觉。
平时一切都很平静，直到某天，甲方的一句“系统是不是出问题了？”
这时候才发现，问题早就埋在那里了。

你登录服务器，开始翻日志、看 trace，一边调试一边回想昨天是不是又改了什么。问题最终解决了，但那种被动的感觉始终在心里。

我后来想：
这种被动，其实是可以被解决的。
有没有可能在客户找上门之前，我就已经知道问题在哪，甚至提前修掉？

为什么我需要它

我手里有不少 PHP 项目，分散在不同的服务器上。
每个项目都有自己的错误日志，但它们互相独立，没人能统一看到全局情况。

想主动检查，就得一台一台地上服务器翻日志。
没出事的时候翻这些日志浪费时间，但不看又怕真的出了问题。

结果就是那种尴尬的状态：
平时不想看，有事的时候措手不及。

我不想再这样。
我希望有一个地方，能让我一眼看到所有项目的错误，集中展示、集中分析。

我想要的样子

我设想的工具应该能做到几件事：

接收所有项目上报的错误信息；
按日期分类保存，支持分页浏览；
可以在浏览器中直接看到最近的错误；
最好还能借助 AI 自动分析错误，帮我快速锁定方向。

这就是 oh-shit-logger 的雏形。

为什么用 Go，而不是 PHP

很多人看到这个项目时会问：
“你不是做 PHP 的？为什么用 Go 写？”

其实原因很简单：我想让它“随拿随用”。

PHP 虽然写起来快，但部署环境太麻烦。不管再怎么简化，总归还是要安装 PHP 环境而 Go 编译出来是一个独立的可执行文件，
上传到服务器就能跑，不用依赖环境，也不用额外配置。

这对我来说非常重要。
我只想有个小程序，能轻轻松松丢到任何服务器上运行，
收集日志、展示信息，不占资源，也不出幺蛾子。

所以最终我选择了 Go。

它现在能做什么

oh-shit-logger 可以在几秒钟内启动。

在 Releases 里下载编译好的版本，上传到服务器后执行：

chmod +x ./app
./app -port=9999 -retain=7 -user=admin -pass=123123

然后访问
http://你的服务器IP:端口号/read
就能看到所有 PHP 项目的错误日志。

PHP 项目上报也很简单，只需要在异常处理中添加一段上报逻辑：

curl_setopt($ch, CURLOPT_URL, 'http://你的服务器IP:端口号/write');

错误信息会被自动收集、格式化、展示，并且可以通过接入的 DeepSeek AI 自动生成分析结果，告诉你错误可能的原因和修复方向。

AI 的部分

我接入 DeepSeek，不是为了给项目贴个“AI标签”。
关于 AI，网上的讨论很多。有人相信它能解决一切，甚至不用写一行代码就能做出完整项目；也有人觉得 AI 看似帮忙，实际上是在暗地里埋雷；还有人担心长期依赖它，会让个人的思考和判断慢慢退化。

我这种小卡拉米肯定是参与不了这种宏大的争论。对我来说，AI 的上下文长度就摆在那里，它要是承担太多工作，难免会丢掉一些细节，而且随着任务量的增加记忆只会越丢越多所以我更愿意把它当成一个“辅助”，就像现在的智能驾驶。它可以给我建议，帮我节省时间，但不要直接动我的东西，最终的决定权还是在我。

有时候我们看到错误信息，稍微一想就知道大概出了什么问题；但也总有那么些时刻，比如正在开会、接电话、或者状态不太好时， AI 能帮我快速过一遍问题，给出大致的方向。这样我可以少花点心力，留点精力去解决真正麻烦的部分。

最后的想法

我做这个项目，其实是为了解决自己的一种焦虑。
那种“系统运行着，但我不知道它哪天会出事”的焦虑。

oh-shit-logger 让我重新掌握了节奏。
现在我不再等客户来告诉我哪里坏了，
我能提前看到问题、分析它、修掉它。

这就是它存在的意义。

项目地址

GitHub: https://github.com/zxc7563598/oh-shit-logger

如果这个项目能帮到你，欢迎点个 Star 或提 Issue。
当然他最好帮不到你，希望你部署之后每天面对的都是一个无数据的空列表 🙏

作为 PHP 开发者，我第一次用 Go 写了个桌面应用

Fri, 26 Sep 2025 07:04:41 GMT

我平时是做 PHP 的，工作里基本上都是在写 Web 应用。说实话，写久了难免有点惯性思维：服务器、框架、数据库、API、浏览器。
而这次，我做了点不一样的东西 —— 一个用 Go 写的财务管理桌面应用。

很多人可能会觉得奇怪：财务管理、记账软件，这不已经烂大街了吗？随便一搜一大堆，为什么还要自己做一个？

我其实一开始也没打算做什么大而全的产品，而是因为一个很小的念头：我想试试 Go 写应用，并打包成 Windows 或 Mac 上能跑的桌面软件。

为什么会有这个念头

PHP 的世界里，几乎绕不开服务器。写一个应用，哪怕功能再小，也得起一个 Web 服务，访问地址可能是 http://localhost:8080，然后浏览器打开用。
这没什么不好，但问题是：

它总归还是个 Web 应用，本地其实只是跑个“假服务器”；
想给别人用，要么部署服务器，要么教别人配环境，挺麻烦；
没法一键生成一个“能直接安装”的应用。

而 Go 给了我一种完全不同的体验：随手 go build，就能编译出一个二进制文件，甚至还能轻松跨平台打包。
这让我很感兴趣，于是就有了这个想法：不如用 Go 写个小工具，然后打包成桌面应用跑跑看。

为什么是财务管理？

那为什么选财务管理呢？因为这个需求对我来说刚好存在。

我平时的开销基本都在支付宝和微信里，虽然它们各自有统计，但没法合并在一起。
我更希望把两个平台的账单统一起来，还能对消费分类做个合并统计，好让我清楚钱都花到哪里去了。

而财务管理这个主题也很适合练手：

前端：做一个管理后台页面，用来录入、展示、统计；
后端：提供账单存储和查询的 API；
再加上：尝试把它打包成桌面应用。

于是我就开工了。

开发过程中的一些体会

做到现在，项目已经算是一个最基础可用的版本了。虽然功能不复杂，但过程里的体会挺有意思。

1. Go 确实很“轻”

写 PHP 的时候，要部署、要跑服务，框架本身也会预先定义很多结构。
而 Go 就很朴素：从监听端口开始，一切都要自己实现。听起来像是会很麻烦，但实际体验完全不是这样。

端口监听、配置文件、路由、中间件……几行代码就能完成。
不仅没有在基建上“浪费时间”的感觉，反而有一种更自由的掌控感。这对我来说很新鲜。

2. 桌面应用和 Web 应用的边界感

虽然这是“桌面应用”，但本质上我还是走前后端分离。
前端在 fintrack-frontend，后端在 fintrack-backend，桌面应用只是“换了个壳子”。
可心理上的感觉不一样：它不再是浏览器地址栏里的东西，而是一个真正“装在电脑上的软件”。

3. 跨语言的思维切换

PHP 写久了，写 Go 的时候会下意识去找框架、找 ORM，结果发现 Go 的生态完全不一样。
刚开始有点别扭，但后来发现语言层面的简洁反而让我能更专注在业务逻辑上，不会被一堆“默认约定”牵着走。

4. 做点“无用”的项目很有意思

说实话，这个财务管理应用对别人来说可能没什么价值，毕竟现成的工具太多了。
但对我来说，它让我尝到了用 Go 做“非 Web 应用”的可能性，也多了一个贴合我需求的小工具。

展望

目前项目已经开源，可以直接下载到安装包：

项目仓库：fintrack-backend

支持打包 Windows 和 Mac 版本，算是实现了我最初的目标。

接下来，我可能会继续加一些功能：

更好看的图表分析；
多账本支持；
导入/导出 CSV；
甚至试试做移动端。

不过，就算后续不再加功能，这个项目也已经达到了我的目的：
它让我走出了 PHP + Web 的惯性思维，尝试了另一种可能。

很多时候，我们写的小项目，在别人看来可能就是“又一个记账软件”，没什么价值。
但对自己来说，它代表的是一个学习过程，一个探索新方向的契机。

所以，如果你也有类似的想法，不妨直接去做。
也许别人不一定用，但你自己的收获，已经足够大了。

用 PHP 玩向量数据库：一个从小说网站开始的小尝试

Sat, 06 Sep 2025 01:02:55 GMT

有时候折腾东西的起因特别随意。比如我这次，就是从一个“带点颜色”的小说网站开始的。网站里全是几万字的短文，看着还不错，但限制也不少：每天只能看几篇，而且没有任何搜索功能。

于是我写了个爬虫，把所有小说都抓了下来。数据一下子堆到本地，看似自由了，但新的麻烦随之而来——几万篇文章放在那里，如果想找某个题材、某种情节，几乎不可能。用关键词搜索顶多能凑合，但语义差一点就找不到，体验并不好。

这时我想到了向量数据库。

为什么用 Milvus

我的服务器规格很小，只有 2 核 2G，根本跑不动本地的 Milvus，更别说大规模向量化了。好在 Milvus 有托管服务，而且带免费额度。这样我就能换个思路：

Mac 本地：用开源模型先做文本向量化，把长篇小说切分成小段（比如 200 个汉字一块），再计算对应的向量。
Milvus 云端：专门存储和管理这些向量，负责后续的相似度检索。
查询时：把搜索词同样向量化，发到 Milvus 去比对，得到语义上更接近的内容。

另外，向量化这一步我用的是 SiliconFlow 提供的模型，免费额度足够支撑实验，算是“白嫖”资源也能玩得转。

为什么要写 PHP 库

可能有人会问：Milvus 不是有 Python、Go SDK 吗？为什么非要用 PHP？

原因其实很简单：我的整个小说爬虫和阅读项目，本身就是用 PHP 写的。再硬插一门语言进去，工程会很乱。于是干脆自己写了一个 PHP 库，把常见的操作封装起来：

创建集合（类似于建表）
插入数据（上传向量和原文片段）
向量检索（传入一个向量，返回相似度最高的结果）
删除集合、清理数据

这样一来，整个流程都能在 PHP 项目里顺利跑通。

怎么用

举个简单的例子。假设我有一段文本 "这是一个测试文本"，先在本地算好向量（这里假设是 [0.12, 0.85, ...]），然后通过库上传：

use Hejunjie\Milvus;

$baseUrl = "http://your-milvus-host"
$apiKey = "your-apikey"

$client = new Milvus\Client($baseUrl, $apiKey);

// 插入数据
$client->entities()->insert("novels", [
    'article_id' => 14271
    'title' => '测试小说',
    'content' => '这是一个测试文本',
    'vector' => [0.12, 0.85, ...]
]);

// 搜索
$results = $client->entities()->search("novels", [
    [0.11, 0.80, ...], // 搜索内容，通过 SiliconFlow 转换为向量
    [0.11, 0.80, ...], // 支持多个数据查询
    [0.11, 0.80, ...]
], 10);
print_r($results);

这样就能查到与输入向量最接近的 10 段文本。通过查询到的 id 就可以在本地数据库中查询对应的小说。对我来说，只要输入大概的剧情方向，Milvus就能把拥有相似片段的小说找出来，比传统关键字搜索好用太多。

支持的方法

这个小库目前支持 Milvus 的常见操作，大致分成几类：

集合（Collections） ：创建、删除、重命名、加载/释放、获取状态、设置属性等。
分区（Partitions） ：创建、删除、加载/释放、查看列表、检查是否存在。
索引（Indexes） ：创建、删除、查看详情，或者列出所有索引。
别名（Aliases） ：创建、修改、删除别名，也可以查看现有别名。
向量数据（Entities） ：插入、更新（upsert）、删除、查询、向量搜索。
其它：比如自定义请求、获取集合的统计信息等等。

简单来说，该有的基本操作都覆盖了，足够支撑一个小型项目的使用。

我的收获

这个库严格来说不算“生产级”，但它让我有一些新的体会：

向量数据库没那么遥远。不一定要做推荐系统或大模型项目，哪怕只是个人的小需求，也能用上。
PHP 也能玩。虽然传统上大家都觉得 PHP 跟 AI 没关系，但只要敢接 API，就能接上去。
动手才有意思。一开始只是因为“不爽”写了个爬虫，后来一步步衍生到向量搜索，最后顺手写了个小库。整个过程不算严肃，但很有乐趣。

所以说，整个过程严格意义上没什么“高大上”的地方，就是一个普通人遇到小问题，忍不住折腾了一下，最后顺手造了个小轮子。

现在呢，我终于可以随心所欲地在几万篇小说里搜索想要的片段了，再也不用翻到眼花还找不到 😂

项目地址 👉 zxc7563598/php-milvusr

RSA+AES 混合加密不复杂，但落地挺烦，我用 Vue+PHP 封装成了两个库

Thu, 28 Aug 2025 11:23:39 GMT

在项目里写接口的时候，我有时候会希望再多一层保护。
虽然 HTTPS 已经能保证传输安全，但它解决的更多是「传输过程中不被窃听/篡改」的问题。
而我还想顺带做到几点：

防止接口被随便模拟调用
就算数据包被截获，也看不懂内容
就算有人拿着同一份请求去重放，服务端也能拒绝

这些需求其实挺常见的，但并不复杂，说白了就是一套 RSA+AES 混合加密。

经典的思路

原理本身没什么新鲜的：

每次请求生成一个随机 AES Key
用 AES 加密数据
再用 RSA 公钥把 AES Key 加密后传给后端
后端用 RSA 私钥解密出 AES Key，再还原请求体

这是标准做法，网上能搜到很多讲解。

真正麻烦的地方

难点其实不在原理，而是在项目里真正用的时候。

比如要自己实现，就得写：

每次生成随机 AES Key
RSA 公钥加密 AES Key
AES 加密/解密请求体
签名计算、时间戳校验，避免重放
各种异常处理（签名错、时间戳过期、解密失败）

单看每一块都不复杂，但组合在一起就有点烦。
而且这些逻辑和业务关系不大，却不得不散落在代码里。

我做的小工具

为了省事，我干脆把它们封装成了前后端两个库：

前端是一个 npm 包
后端是一个 PHP 的 Composer 库

目标就是：用起来跟普通请求没什么两样，但底层自动帮你做了加解密和校验。

用法示例

前端：

npm install hejunjie-encrypted-request

import { encryptRequest } from "hejunjie-encrypted-request";

# 不建议在代码里写死公钥，建议通过读取文件来获取公钥字符串
const encrypted = encryptRequest({ name: "张三" }, {
  publicKey: "-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----",
});

request.post("/api/user/info", encrypted)
  .then(res => console.log(res));

后端：

composer require hejunjie/encrypted-request

use Hejunjie\EncryptedRequest\EncryptedRequestHandler;

// 自行在中间件或方法前完成请求参数的获取
$param = $_POST;

// 同样不建议代码里写死私钥
// 要么私钥作为 RSA_PRIVATE_KEY 放在.env里（此方法就无需再传递$config）
// 要么直接读取文件作为配置传递
$config = [
    'RSA_PRIVATE_KEY' => file_get_contents(private_key.pem)
];
$handler = new EncryptedRequestHandler($config);
$data = $encrypted->handle($param['en_data'] ?? '', $param['enc_payload'] ?? '', $param['timestamp'] ?? '', $param['sign'] ?? '');

print_r($data); // ['name' => '张三']

开发者只需要像平时一样写请求，库会自动处理 AES/RSA 加解密、签名、时间戳校验、异常。

适合的场景

这个方案当然不是替代 HTTPS，而是作为额外的一层保护：

内部系统，不希望接口被随便重放/模拟
中小项目，对安全有点额外要求，但不想上很重的安全框架
想快速把 RSA+AES 混合加密落地，而不用自己重复造轮子

仓库地址

前端仓库：npm-encrypted-request
后端仓库：php-encrypted-request

希望能帮到和我一样遇到类似需求的人。

订单号老是撞车？我写了个通用 PHP ID 生成器

Sat, 23 Aug 2025 01:02:10 GMT

在日常开发里，我们经常会遇到这种情况：

需要给订单生成唯一编号；
想给日志或者资源加个标识；
或者需要一个不会重复的 ID，用作数据库主键。

一开始，我也用过 time() 拼接随机数、或者 uniqid()。
这些方案在小项目里够用，但一旦放到并发稍微高点的业务里，就会出现各种问题：

time() 很容易撞车（同一毫秒可能生成多个）；
uniqid() 看上去独特，其实也可能重复，而且格式不太好看；
有些场景希望 ID 可读，比如订单号，最好一眼能分辨。

久而久之，我在不同项目里反复造轮子，干脆就写了一个通用的小工具，把常见的 ID 生成方式都封装起来了。

这个工具能做什么？

它支持几种常见的生成策略：

1. Snowflake（雪花算法）

经典的分布式 ID 算法；
生成的 ID 在高并发下也能保持唯一。

use Hejunjie\IdGenerator\IdGenerator;

$generator = new IdGenerator::make('snowflake')
$id = $generator->generate();

echo $id; // 233953299479035905

还能解析出来生成时间、机器 ID 等信息，排查问题时很方便。

2. Timestamp（时间戳 ID）

由时间戳+序列号构成；
可以加前缀，比如生成订单号：

use Hejunjie\IdGenerator\IdGenerator;

$generator = new IdGenerator::make('timestamp', ['prefix' => 'ORD']);
$id = $generator->generate();

echo $id; // ORD1755778813238294503

3. Readable（可读 ID）

格式类似：ORD-20250822-abcdef12；
适合展示给用户，更容易记忆。

use Hejunjie\IdGenerator\IdGenerator;

$generator = new IdGenerator::make('readable', ['prefix' => 'ORD', 'randomLength' => 6]);
$id = $generator->generate();

echo $id; // ORD-2025-08-21-7ABP01

4. UUID

熟悉的 UUID v1/v4；
通用，跨系统时尤其常见。

use Hejunjie\IdGenerator\IdGenerator;

$generator = new IdGenerator::make('uuid', ['version' => 'v4']);
$id = $generator->generate();

echo $id; // ad0f5dfc-4a3d-4c2a-853b-aa3a3d9062aa

5. 自定义策略

如果你想要特别的格式，比如 USER-随机数，也能自己实现。

use Hejunjie\IdGenerator\Contracts\Generator;
use Hejunjie\IdGenerator\IdGenerator;

class MyCustomGenerator implements Generator
{
    public function __construct(private string $prefix = 'MY') {}

    public function generate(): string
    {
        return $this->prefix . '-' . random_int(1000, 9999);
    }
    public function parse(string $id): array
    {
        return ['id' => $id];
    }
}

IdGenerator::registerStrategy('custom', function (array $config) {
    return new MyCustomGenerator($config['prefix'] ?? 'MY');
});

$generator = new IdGenerator::make('custom', ['prefix' => 'ORD']);
$id = $generator->generate();

echo $id; // ORD-4128

为什么要做这个库？

没有什么“高大上”的理由，就是因为自己项目里老是遇到这种需求：

想要一个统一的生成方式，避免东拼西凑；
想要可扩展，方便以后加新的策略；
想要轻量，直接安装就能用，不依赖庞大的框架。

于是就写了这么个东西，后来觉得或许对别人也有用，就开源了。

安装方式

composer require hejunjie/id-generator

最后

这个小工具库目前还是 v1.0.0，功能比较基础。
如果你在项目里也有类似需求，可以拿来试试看。
要是你有更好的想法（比如加 ULID、新的生成算法等），非常欢迎提 PR 或者 Issue，一起完善。

项目地址 👉 zxc7563598/php-id-generator

舰长积分商城和弹幕机器人系统的手动部署教程

Sun, 17 Aug 2025 11:47:11 GMT

有感觉到文章很乱吗？虽然不知道你怎么想但反正我是有点感觉到了。

不同时间出了好几个教程管理起来真的很麻烦。

我把所有相关的内容放到了一个文档中：点击前往

今天给大家带来的是舰长积分商城和弹幕机器人系统的手动部署教程。

之前我出过一个“一键部署”的版本。
但是有不少小伙伴反馈说，不太想用 Docker，或者想直接在自己的设备上部署，所以更希望能一步一步手动安装。

这次我就从零开始，带大家完整走一遍手动部署的流程。

功能简介

这个系统主要有两个功能：

积分商城：舰长上舰后自动记录积分，积分可在商城里兑换奖品；
弹幕机器人：支持自动感谢礼物、关注、进房、分享，还能播报大乱斗对手房间情况。

所有数据都在你自己的服务器里，不需要担心审核或数据泄露，也不会有任何收费问题，完全免费。唯一的成本就是准备一台云服务器。

当然，如果你完全不懂代码，更推荐先看我之前的“一键部署”教程，会更省事。

如果你选择手动部署，不管你是折腾群晖也好，在Windows环境下跑虚拟机也罢，我默认你是一个多少懂一点基础的朋友。

记得在部署的过程中解决科学上网的问题，因为代码托管也好，项目中一些扩展的安装也好，难免会用到大陆以外的资源。

如果遇到问题我非常乐意在空闲时间帮大家解决问题，但是网络问题这种我确实没有什么好办法，这个东西比较敏感，也不太好教 🙏

Step 1：安装宝塔面板

首先，我们需要在服务器上安装宝塔面板。

安装完成后，宝塔会显示登录地址、用户名和密码。用这些信息登录，就能进入服务器的管理面板。

Step 2：安装运行环境

登录宝塔后台，进入 软件商店，依次安装：

Nginx（默认版本）；
PHP 8.2；
MySQL 8.0（注意不要用默认版本）；
Redis（默认版本即可）

安装需要一些时间，大家耐心等待，完成后，如下图所示。

完成后，还需要做以下配置：

在 PHP 设置中安装扩展：redis、event；

在配置文件中搜索：disable_functions ，内容替换为：

disable_functions = passthru,system,chroot,chgrp,chown,ini_alter,ini_restore,dl,openlog,syslog,readlink,symlink,popepassthru

在 pecl扩展安装 处安装 brotli
进入数据库，修改 root 密码为一个你自己能记住的值。

Step 3：创建数据库

在终端输入：

mysql -u root -p

输入刚刚设置的密码后，执行以下命令创建数据库：

CREATE DATABASE bilibili_danmu CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Step 4：下载项目

在宝塔后台打开 文件 → 终端，输入：

git clone https://github.com/zxc7563598/php-bilibili-danmu

刷新页面后，可以看到多了一个 php-bilibili-danmu 文件夹。

进入该文件夹，新建 .env 文件（前面有点）。

然后打开 .env.example，复制内容到 .env 并修改：

系统服务地址：服务器IP:7777
加密配置：随意输入 16 位字母或数字（数字密钥、初始向量同样 16 位）
主密钥：随意输入 32 位字母或数字
商城前台访问地址：服务器IP:5177
项目监听端口：7776
API 密钥：随意输入 32 位字母或数字
数据库配置：数据库名（bilibili_danmu）、用户名（root）、密码（你修改的 root 密码）

保存后，配置完成。

Step 5：安装依赖并启动

在终端执行（一行一行执行）：

composer install

php vendor/bin/phinx migrate -e development

php start.php start -d

这样依赖安装、数据库构建、项目启动就完成了。

Step 6：配置机器人站点

进入宝塔后台 → 网站 → 添加站点：

域名：服务器IP:7777
根目录：php-bilibili-danmu

创建后，进入站点设置 → 配置文件，在顶部添加：

upstream bilibilidanmuji {
    server 127.0.0.1:7776;
    keepalive 10240;
}

保存后，再进入伪静态，添加：

location ^~ / {
  proxy_set_header Host $http_host;
  proxy_set_header X-Forwarded-For $remote_addr;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Real-IP $remote_addr;
  proxy_http_version 1.1;
  proxy_set_header Connection "";
  if (!-f $request_filename){
    proxy_pass http://bilibilidanmuji;
  }
}

最后在网站目录设置中：

关闭防跨站攻击；
将运行目录改为 public；
保存即可。

这时，访问 服务器IP:7777 就能进入机器人控制台。

Step 7：配置积分商城

宝塔后台 → 网站 → Node项目安装Node：

设置命令行版本：

进入机器人控制台，点击 构建商城

看到这样的内容说明成功：

然后在宝塔后台 → 网站 → 新建站点：

域名：服务器IP:5177
根目录：php-bilibili-danmu/public/shop/dist
PHP 版本：纯静态

创建后，进入伪静态，填入：

location / {
  try_files $uri $uri/ /index.html;
}

保存后，访问 服务器IP:5177 即可进入积分商城。

🎉 至此，手动部署就全部完成啦！
机器人和积分商城都可以正常使用，大家可以根据需要进行进一步配置。

关于一键部署

可能不是最完美的方案，但它一定是对新手最友好的选择：一键配置，命令执行后静待完成，项目会自动拉取、配置并保持更新，全程无需额外操作。

在你的服务器上执行：

curl -fsSL https://bilibili-danmu-scripts.oss-cn-hongkong.aliyuncs.com/install-docker.sh | bash

没有开发基础的用户 请确保您使用的是阿里云位于香港地域的 Ubuntu 24.04 64 位 版本的服务器。这是一套经过验证的环境，能最大程度减少部署问题

其他云服务商或系统版本未做兼容性测试，不排除出现问题的可能性。如果你遇到问题，可以来问我，我乐意帮忙，全当交个朋友。但不保证解决。

一键部署脚本写得很简单，不依赖复杂逻辑，有动手能力的用户完全可以自行调整环境。完全不懂的朋友，建议按推荐配置来，别自找麻烦。

不会购买服务器看下方「一些问题」中的「关于购买服务器」

购买服务器不知道如何使用的看下方「一些问题」中的「购买了服务器要如何使用」

关于购买服务器

为什么要购买服务器？

这不是一个传统意义上的“机器人”项目。如果你只是需要一个弹幕助手，确实可以直接在自己的电脑上运行，直播时连上直播间，下播后关掉就行。

但这个项目是一个积分商城，实质上就是你自己的一个网站。它需要 24 小时持续运行，并且对外开放，让观众随时都能访问和使用。所以，和普通机器人不同，它需要部署在一台能够长期在线、稳定对外服务的服务器上。

如何购买服务器？

前往阿里云云服务器 ECS 控制台 → 点击「创建实例」 → 选择合适的配置进行购买。

以下是推荐配置说明：

地域：请选择 中国香港（具体原因详见下方章节 “为什么选择香港服务器”）
配置：最低建议选择 2 vCPU + 2 GiB 内存。计算型、共享型等都可，不推荐“突发性能实例” ，这类机型在大多数时间会限制 CPU 性能，影响使用体验。
系统镜像：请选择 Ubuntu 20.04 64位，我所有的测试与部署都基于此版本，兼容性和稳定性最好。

其他配置可根据个人需求自行选择，不过如果你是第一次使用，建议直接参考上图进行配置，省事也稳妥。

关于为什么要选择香港服务器

备案麻烦 & 使用限制：
大陆地区的服务器对外提供互联网服务时，必须完成备案和一系列合规流程，流程繁琐，还会受到一定的监管。相比之下，香港属于中国，却不需要备案，开箱即用、稳定省事。
至于日本、韩国等境外服务器，由于科学上网问题，连接经常不稳定，不推荐新手使用。
代码托管在 GitHub：
如果你选择一键部署，服务器需要从 GitHub 拉取代码，而 GitHub 并不在国内。
大陆服务器与个人一样也会受到网络限制，可能导致部署失败。

小提示：如果你打算在自家的服务器、NAS 或虚拟机中部署，请务必先解决访问 GitHub 的问题。
实用角度考虑：
其实用国内服务器也不是不能用，就是容易自找麻烦。
阿里云香港的稳定性不错，部署项目之外还能顺便搭个梯子。虽然 ChatGPT 屏蔽了香港 IP，但看点其他内容、搭建加速服务还是很香的，明码标价、速度稳定，视频都能流畅播放。

如果你不懂怎么搭梯子，欢迎私聊，我可以教你。

购买了服务器要如何使用

可以通过 FinalShell 远程连接直播间：点击下载

关于怎么才能让访问地址变成网址而不是IP

需要购买域名进行绑定

为什么需要域名？

没有域名也能访问你的网站，正常情况下就是通过 http://你的服务器IP:7777 来访问后台管理，商城则是 http://你的服务器IP:5177。

这当然可以用，如果你不介意链接不好看，也可以直接生成二维码发给观众扫码，访问是没有任何问题的。

但从使用体验来说，IP 地址链接就像毛坯房一样：
丑、不好记、不专业、不安全。

就像百度的 IP 地址是 http://39.156.70.46，你能访问它没错，但肯定没人会去记这个地址。相比之下，https://baidu.com 简洁、有辨识度、安全性也更高。

所以，域名的意义不只是“能访问”，而是让你的项目看起来像个“成品”而不是“内测工具” 。而且现在域名注册成本也不高，是值得的投入。

如何购买域名？

域名注册的平台有很多，比如 GoDaddy 和阿里云都是业内比较成熟、可靠的选择。

如果你已经在阿里云购买了服务器，那直接在阿里云顺手把域名也买了会更方便。购买流程不复杂：
搜索你想要的域名，看看有没有被注册，没被注册就可以直接下单购买。

注意： 在阿里云购买域名时需要先完成实名认证，流程不麻烦，按照提示提交资料即可。不需要备案，只是做个身份验证。

另外提醒一下：
如果你的服务器不是香港而是中国大陆地区的，那我通常不建议你单独买域名。因为域名如果解析到大陆服务器，必须完成 ICP 备案，这个流程需要向工信部提交材料，耗时大约 20 个工作日左右。

而且如果你是个人备案，只能用于“博客类”网站，像这种积分商城类项目是无法备案的，必须使用企业主体才能通过。

购买域名后如何使用

购买域名后，请前往阿里云域名列表：

找到你购买的域名 → 点击“操作” → 选择“解析” → 进入添加记录页面

在“添加记录”页面中，大部分设置（如记录类型、解析线路、TTL）保持默认即可，只需要关注以下两个字段：

主机记录：即你想绑定的子域名前缀。例如你的域名是 hejunjie.life，这里填写 asd，那最终用户访问的地址就是 asd.hejunjie.life
记录值：填写你服务器的公网 IP 地址

你需要添加 两个解析记录 指向你的服务器：

一个用于访问 机器人后台
一个用于访问 积分商城

⚠️ 域名解析通常需要几分钟时间才能生效，建议等待 10 分钟左右 确保解析成功。

✅ 解析成功后，登陆服务器配置域名和 SSL 证书即可

如何配置服务器域名和 SSL 证书

一键部署版

解析完成后，登录你的服务器，执行以下命令完成自动配置（包括 Nginx 和 SSL）：

curl -fsSL https://bilibili-danmu-scripts.oss-cn-hongkong.aliyuncs.com/setup-nginx-ssl.sh | bash -s 后台地址 积分商城地址 你的邮箱

之后完成后续步骤即可

手动部署版

前往宝塔面板 -> 网站，可以看到手动部署时你设置的机器人站点（后台站点）跟积分商城站点

对应的站点点击设置，在域名位置（原本手动部署中写服务器IP:7777跟服务器IP:5177的位置）添加解析的网站地址

后台站点添加后台地址，积分商城添加积分商城地址

“后台地址”和“积分商城地址”就是你刚才解析的域名，例如：asd.hejunjie.life

添加完成后选择 SSL，切换到 Let's Encrypt 标签页

勾选添加的域名，申请证书，即可完成配置

之后完成后续步骤即可

后续步骤

执行成功后，进入机器人后台控制台 → 打开「系统配置」：

修改 项目地址 为：https://后台的地址
修改 商城地址 为：https://积分商城的地址

“后台地址”和“积分商城地址”就是你刚才解析的域名，例如：asd.hejunjie.life

例如你填的是 asd.hejunjie.life，那就改为：

https://asd.hejunjie.life

配置完成后，你就可以通过浏览器访问：

控制台后台：https://后台的地址
用户商城：https://积分商城的地址

关于独立后台

仓库地址：点击查看

现在的机器人实际上已经内置了一个原生后台，已可直接使用，此项目非刚需。本项目的目标是为追求更强大后台功能的用户提供一个更完善的替代方案。

由于在推荐服务器配置时出于成本考虑，建议使用较低配置的服务器（如 2 核 2G）。这种配置在实际运行项目时并不会有明显问题，但如果尝试在服务器上直接构建本项目，性能压力会非常大，构建过程可能会失败甚至卡死。

因此，我们将前端后台代码单独抽离到此仓库，建议用户在本地完成构建后再上传到服务器。这并不是一项复杂的操作，欢迎动手尝试，如有困难也可以联系作者获取帮助。

部署方式

# 1. 下载项目
git clone https://github.com/zxc7563598/vue-bilibili-danmu-admin.git
# 然后你就会得到一个 vue-bilibili-danmu-admin 目录，这个就是整个项目了
# 前往这个目录


# 2. 安装 Node.js
# 请前往官网下载安装适合你系统的版本：https://nodejs.org/zh-cn
# 目的是为了可以在终端使用 npm 命令
# 过低版本的 NodeJs 的 ESM 模块在 Windows 上对绝对路径支持不完善，可能会出现问题
# 所以尽量不要去装过低的版本，起码要在 18+ 以上才不会有问题

# 3. 配置环境变量：复制 `.env.example` 为 `.env`
# 这里有很多朋友没搞明白
# 其实就是你下载下来的项目中，会存在一个 .env.example 文件，这个是配置的模板文件，教你怎么配置的
# 我们需要在 vue-bilibili-danmu-admin 中创建一个 .env 然后把 .env.example 文件里的内容复制一份过去
# .env 里面的内容需要手动替换
# 根据实际情况填写请求地址、密钥等信息，具体信息可在机器人控制台系统配置中查看。

# 4. 安装依赖 & 构建项目
# 这里也有朋友翻过车，要在 vue-bilibili-danmu-admin 目录去执行这个命令哦
npm install
npm run build

# 执行后将生成 `dist/` 目录，即为最终可部署版本

# 自动部署：将此目录上传到 `/opt/bilibili-robots/php/public` 目录中，重新访问机器人控制台，即可自动切换到新版后台。
# 手动部署：将此目录上传到 `/www/wwwroot/php-bilibili-danmu/public` 目录中，重新访问机器人控制台，即可自动切换到新版后台。

# 使用新版后台的过程中，删除 `/项目目录/public/dist` 目录即可停用新版后台、切换回老版本后台

如何让同事自己查数据？写一个零依赖 PHP SQL 查询工具就够了

Sun, 17 Aug 2025 07:10:37 GMT

在公司里，运营、老板或者其他同事经常会来找我问数据。很多时候，一个简单的 SQL 就能解决问题，但他们从来不愿意学 SQL，也不想安装任何查询工具。每次被打断写代码，我都非常无奈。

于是，我写了一个小工具——Data Query Tool，让同事自己动手查数据，自己专心写代码，同时还能保证简单、快速、安全。

问题

同事不会 SQL，也不想学。
安装数据库客户端工具成本高，不方便在每台电脑上部署，哪怕是 phpMyAdmin 他们都不愿意去了解。
每次帮人查数据都很耗时间，打断了开发思路。

我希望的是：让非技术同事可以在浏览器里直接点击，就得到他们想要的数据，最好还能导出 Excel，省的来找我要数据。

解决方案

我选择了用 PHP 写一个零依赖、无框架、单文件启动的查询工具：

只要把代码放到服务器上（最好是公司内网），运行：
```
php -S 0.0.0.0:8000
```
就可以通过浏览器访问 http://服务器IP:8000。
常用 SQL 配置成模板，支持参数化：
- 文本输入（input）
- 日期选择（date）
- 下拉选择（select）
同事直接选择 SQL 模板、填入参数，就能查询，不用写 SQL。
内网部署安全可靠，零打扰开发流程。

SQL 配置说明

工具使用 config.json 来管理 SQL 模板，结构示例：

{
  "sql_templates": [
    {
      "name": "查询所有用户",
      "query": "SELECT user_id as '用户ID',phone as '手机号',real_name as '姓名',FROM_UNIXTIME(created_at) as '创建时间' from ch_users where deleted_at is null",
      "query_params": {}
    },
    {
      "name": "根据手机号查询用户",
      "query": "SELECT user_id as '用户ID',phone as '手机号',real_name as '姓名',FROM_UNIXTIME(created_at) as '创建时间' from ch_users where phone = {{phone}} and deleted_at is null",
      "query_params": {
        "phone": {
          "type": "input",
          "description": "手机号"
        }
      }
    },
    {
      "name": "根据注册时间查询用户",
      "query": "SELECT user_id as '用户ID',phone as '手机号',real_name as '姓名',FROM_UNIXTIME(created_at) as '创建时间' from ch_users where created_at >= UNIX_TIMESTAMP({{start_time}}) and created_at <= UNIX_TIMESTAMP({{end_time}}) and deleted_at is null",
      "query_params": {
        "start_time": {
          "type": "date",
          "description": "开始时间"
        },
        "end_time": {
          "type": "date",
          "description": "结束时间"
        }
      }
    },
    {
      "name": "根据订单状态搜索订单信息",
      "query": "SELECT borrow_sn as '订单号',real_name as '姓名',borrow_amount as '合同金额',FROM_UNIXTIME(created_at) as '签约时间' from ch_borrows where `status` = {{status}} and deleted_at is null",
      "query_params": {
        "status": {
          "type": "select",
          "options": [
            { "value": "5", "label": "拒绝签约" },
            { "value": "6", "label": "取消签约" },
            { "value": "9", "label": "签约失败" },
            { "value": "11", "label": "已签约" },
            { "value": "12", "label": "已完成" }
          ],
          "description": "订单状态"
        }
      }
    }
  ]
}

说明：

query 中用 {{参数名称}} 占位

query_params 定义参数类型、说明、可选项

支持 input / date / select 三种输入方式

页面会根据参数类型自动生成相应控件，非技术同事也能操作

使用示例

将代码放到服务器或电脑

git clone https://github.com/zxc7563598/data-query-tool.git
cd data-query-tool

启动 PHP 内置服务器
```
php -S 0.0.0.0:8000
```
浏览器访问
打开 http://服务器IP:8000
- 选择 SQL 模板
- 填写或选择参数
- 点击查询，即可显示结果
可选：编辑 config.json
- 配置 SQL 模板
- 配置模板参数类型和描述

效果截图

总结

其实也没啥高大上的理由，我写这个工具就是因为——老板和同事再也不会天天来烦我查数据了。

他们想要啥，自己点点就行；我也不用被一行 SQL 打断思路。

说白了，这东西就是 给自己图个清净。

如果你也遇到类似的场景，可以在评论区聊一聊。
说不定我能帮你顺手做个小工具，也算是给我自己省点事 —— 毕竟我一个人可能发现不了那么多“被烦”的场景。

我写了个脚本，统计了我自己写了多少行代码（纯图一乐）

Fri, 08 Aug 2025 09:48:49 GMT

为什么要做这件事？

老实说，我平时不太在意自己到底写了多少行代码。

一方面是因为这东西真没啥太大参考价值，想刷行数的话，复制粘贴个几千行都不是事；另一方面也是因为谁都知道：代码质量和行数没什么关系。

但有时候，好奇心就是挡不住。
就像你听到别人讲“十万小时定律”的时候，会突然想：

“哎，那我到底练习了多久？”

我写代码已经很多年了，也做了不少项目，大部分都丢在 GitHub 上没怎么管过。突然有天我就想：
“我这几年到底写了多少行代码？”

没什么远大目标，也不是为了攀比，就是想统计一下，纯图一乐。

发现了一个小工具：`cloc`

为了满足这个好奇心，我去搜了一下有没有能统计代码行数的工具，结果发现了一个叫 cloc 的小东西。

用起来特别方便，直接在命令行跑一下，它就会帮你统计：

每种语言用了多少文件；
每种语言写了多少代码行；
有多少注释行、空白行；

而且输出格式非常清爽，长这样：

-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
PHP                            213           4521           2349          19432
JavaScript                      75           1833           1102          10231
...

看着还挺有成就感的（笑）。

但问题是：我的代码都在 GitHub 上

工具虽然好用，但有个问题：

我的代码都放在 GitHub 上，平时根本没下载到本地，如果我想统计，就得先一个个仓库 clone 下来，太麻烦了。

所以我干脆就写了个脚本，把整个流程自动化了。

脚本主要做了三件事：

通过 GitHub 官方的 gh 命令获取我账号下的所有仓库；
把这些仓库一个个同步到本地（已有就 pull，没有就 clone）；
然后用 cloc 统计整个目录的代码行数，并排除掉构建/依赖目录。

简单说，就是把 GitHub 上的项目都打包带回家，然后用 cloc 数一数。

工具准备（支持 macOS / Ubuntu / Windows）

这个脚本依赖以下几个命令行工具：

gh：GitHub CLI，用于获取仓库列表；
jq：命令行 JSON 解析工具，用于处理接口返回的数据；
cloc：统计代码行数的小工具；
git：当然少不了，用来 clone 仓库。

macOS 安装方法（用 Homebrew）：

brew install gh jq cloc git

Ubuntu / Debian 安装方法：

sudo apt update
sudo apt install gh jq cloc git

Windows 安装方法（建议用 WSL）

Windows 用户建议安装 WSL（Windows 子系统）并使用 Ubuntu：

在 PowerShell（管理员）运行：
```
wsl --install
```
安装完成后打开 Ubuntu；

安装依赖：

sudo apt update
sudo apt install gh jq cloc git

GitHub CLI 登录一次（非常重要）

运行脚本前，请先登录 GitHub CLI：

gh auth login

它会引导你通过浏览器进行一次性授权。

脚本源码（可以直接用）

#!/bin/bash

USERNAME="zxc7563598"   # 👈 改成你的 GitHub 用户名
WORKDIR="$HOME/github_repos"

# 创建存放仓库的目录
mkdir -p "$WORKDIR"
cd "$WORKDIR" || exit

echo "📥 正在获取 $USERNAME 的所有仓库..."

# 获取所有仓库的 HTTPS 地址（最多 200 个，可改成 1000）
gh repo list $USERNAME --limit 200 --json nameWithOwner,url \
  | jq -r '.[].url' | while read repo; do
    reponame=$(basename "$repo")
    if [ -d "$reponame" ]; then
        echo "🔄 更新仓库: $reponame"
        cd "$reponame" && git pull --quiet && cd ..
    else
        echo "⬇️ 克隆仓库: $reponame"
        git clone --depth=1 "$repo" --quiet
    fi
done

echo ""
echo "📊 开始统计代码行数（排除 node_modules、vendor、dist、build、public）..."
echo ""

cloc --exclude-dir=node_modules,vendor,dist,build,public --exclude-lang=JSON .

运行结果展示

执行脚本后，大概就会看到类似这样的输出结果（我的结果）：

-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
PHP                           2334          14079          60356         613174
Vuejs Component                232           2273           1207          29480
JavaScript                     198           2769           2813          16292
CSS                             13           1566            182          13460
YAML                            15           3345              1          12314
HTML                            43            507            262          11776
Markdown                        52           1881             11           4773
Blade                           27            386             52           3942
Go                               4             80             65            887
WXSS                            10            118             19            753
Bourne Shell                     7            106            104            415
SVG                            350              0              0            415
WXML                             9              7             16            295
Protocol Buffers                 1              2              0            187
C                                1              6              0            101
Python                           1             32             29             91
XML                              1              0              2             29
INI                              2              4              0             20
Dockerfile                       1              1              0              5
DOS Batch                        1              0              0              3
CSV                              1              0              0              2
-------------------------------------------------------------------------------
SUM:                          3303          27162          65119         708414
-------------------------------------------------------------------------------

当然，如果你并不像我一样需要从 GitHub 上同步仓库，那你大可不需要使用我的脚本，只需要在你想要统计的目录下执行 cloc . 就好了

是不是还挺有意思的？
虽然知道这个数字没啥特别实质意义，但看着这些年自己写的几万行代码，有点像翻相册的感觉。

总结一下

cloc 是一个小巧但非常实用的代码行数统计工具；
如果你的项目都放在 GitHub 上，可以配合 gh 做自动化统计；
虽然代码行数并不重要，但偶尔看看还是挺开心的；

就当是一种和过去的自己打个招呼吧 ——
“嘿，我还在写代码，而且已经写了好多年了。”

构建一个简洁优雅的 PHP 参数验证器 —— php-schema-validator

Thu, 07 Aug 2025 07:36:11 GMT

在日常开发中，参数校验是绕不过的一道坎。我们常常需要确保用户传入的数据符合预期格式，比如必填字段、数据类型、最大长度、邮箱格式等等。虽然许多 PHP 框架都内置了验证器，但在开发轻量服务、非框架项目，或需要在业务中后端进行结构化数据校验时，我总觉得现有方案不够灵活、冗余较多。

于是，我动手写了一个开箱即用、易扩展、轻量级的参数验证器：php-schema-validator

为什么要造这个轮子？

虽然 PHP 社区有很多验证类库（如 Laravel 的 Validator、Respect\Validation、Opis JSON Schema 等），但它们往往：

要么依赖框架，不方便独立使用；
要么语法冗长，无法用简洁的规则表达复杂校验；
要么扩展性差，自定义规则成本高。

我想要一个东西，既能用类似 JSON Schema 的方式表达规则，又能非常容易地扩展，同时尽量保持核心代码简洁明了。
于是这个项目诞生了。

核心设计理念

这个库的核心目标可以总结为三句话：

规则驱动 —— 用数组描述你的字段规则，声明式更直观；
可扩展 —— 每一个验证规则都是独立的类，插件化设计；
无依赖 —— 不依赖框架，适用于任意 PHP 项目。

安装方式很简单：

composer require hejunjie/schema-validator

一个简单示例：

use Hejunjie\SchemaValidator\Validator;
use Hejunjie\SchemaValidator\Exceptions\ValidationException;

$data = [
    'name'   => '张三',
    'age'    => 28,
    'email'  => 'invalid-email',
];

// 自定义扩展，返回 true 则规则通过，否则均视为不通过
Validator::extend('is_zh', function ($field, $value, $params = null) {
    if (preg_match('/^[\x{4e00}-\x{9fa5}]+$/u', $value)) {
        return true;
    }
});

try {
    Validator::validate($data, [
        'name'  => ['is_zh', 'string', 'minLength:2'],
        'age'   => ['integer', 'between:18,60'],
        'email' => ['required', 'email'],
    ]);
    echo "验证通过 ✅";
} catch (ValidationException $e) {
    echo "验证失败 ❌" . PHP_EOL;
    print_r($e->getErrors());  // 友好打印错误信息
}

输出类似：

验证失败 ❌
Array
(
    [email] => Array
        (
            [0] => email
        )

)

支持的验证规则

目前内置了这些基础规则（并持续扩展中）：

类型类：支持 string / integer / boolean / array / object / float / numeric
比较类：支持 min / max / between / length / min_length / max_length / gt / lt / gte / lte
格式类：支持 email / mobile / url / ip / json / alpha / alpha_num / alpha_dash
布尔类：支持 required / accepted / declined
自定义类：支持 starts_with / ends_with / contains

如何扩展一个自定义规则？

比如我想加一个 is_zh（只允许输入中文）规则：

use Hejunjie\SchemaValidator\Validator;

// 在调用 Validator::validate 之前
Validator::extend('is_zh', function ($field, $value, $params = null) {
    if (preg_match('/^[\x{4e00}-\x{9fa5}]+$/u', $value)) {
        return true;
    }
});

然后就可以直接使用：

use Hejunjie\SchemaValidator\Validator;
use Hejunjie\SchemaValidator\Exceptions\ValidationException;

try {
    Validator::validate($data, [
        'name'  => ['is_zh'],
    ]);
	// 验证成功
} catch (ValidationException $e) {
	// 验证失败
}

如果有常用自定义规则，建议在代码中封装 Validator::validate 方法，在调用 validate 之前通过 extend 方法注册自定义规则

在常驻内存的项目中，建议在项目运行初始化时全局注册，以减小性能开销

项目地址 & 使用方式

GitHub 仓库地址：
🔗 https://github.com/zxc7563598/php-schema-validator

欢迎 Star、提 Issue、提 PR！

下一步计划

我还在考虑以下几点：

错误信息多语言支持
Laravel / Webman / Hyperf 插件适配
添加更多内置规则（银行卡号、身份证号、UUID 等）
将 schema 校验支持 YAML / JSON 文件描述

最后

这是一个“造轮子”项目，但也是一个“实践设计”的项目。如果你也曾因为参数验证的重复劳动而烦恼，不妨来试试这个轻量、可扩展的验证器。

如果这个库对你有帮助，欢迎 Star、提建议或一起共建 🚀

如何优雅地处理多种电商优惠规则？我用 PHP 封装了一个 Promotion Engine

Fri, 01 Aug 2025 05:49:04 GMT

做电商项目时，经常要处理各种各样的优惠活动：满减、打折、VIP 专属优惠、第二件特价、阶梯优惠……
这些单独实现起来都不复杂，但当你把它们放在一起，就变得混乱起来了。

我自己在工作里写过不少类似的逻辑，每次做法差不多：if/else、switch、各种判断混在一起，过几个月回头看代码，根本不想维护。
于是我干脆写了一个小库，封装了常见的优惠计算逻辑，让这件事更清晰，也能随时在别的项目里用——php-promotion-engine 就是这样来的。

为什么要做这个东西？

一个简单的例子：

购物车里有满 200 减 50 的活动

VIP 用户可以再打 9 折

某些商品买三件还能再减 20

这三个优惠叠在一起，怎么算？

是每条规则单独算优惠，最后加在一起？
还是「满减后再打折」的折上折？
或者一件商品只能享受其中一种优惠？

业务里经常会遇到这些问题，而我不想再每个项目都重新造轮子，所以就抽了一个核心逻辑出来，做成 Composer 包。

我把优惠计算分成了三种模式

1. 独立模式（independent）

每条优惠规则都基于商品原价独立计算优惠金额，最后把这些金额加起来。

特点：

所有优惠平行计算，彼此之间没有影响
优惠金额往往会比较大（因为每条规则都按原价算）
运营活动彼此独立时，通常用这种模式

例子：

购物车 300 元，满 200 减 50，VIP 9 折
「满减」算 50 元优惠
「VIP」算 30 元优惠（300元 - 300 元 × 0.9）
最后优惠金额是 80 元，结果是 220 元

2. 折上折模式（sequential）

这里的优惠是「顺序计算」的，每条规则会根据上一条规则之后的价格来继续打折或满减。

很多电商活动是顺序叠加的，比如「满减后再打折」，这就是折上折模式的用武之地。

特点：

优惠金额会按比例分摊给参与优惠的商品，并实时更新商品价格
下一条规则拿到的是更新后的价格，真正意义上的“折上折”
可能出现这样一种情况：
- 原价满足满减 → 满减后价格降低 → 后面的优惠金额也变少
也可能出现：
- 某个商品满减后价格降低，下一条满减规则再也不满足条件

例子：

购物车 300 元，满 200 减 50，VIP 9 折
「满减」算 50 元优惠
「VIP」算 25 元优惠（250 元 - 250 元 × 0.9）
最终优惠金额是 75 元（比独立模式的 80 元少）

3. 锁定模式（lock）

这个模式更“严格”——每件商品最多只能享受一条优惠规则。
一旦被某个优惠“锁定”，这件商品就不再参与其他规则的计算。

特点：

适用于「只能享受一次优惠」的场景（比如秒杀、专属券）
优惠不会叠加，运营逻辑更容易控制

例子：

A 商品被秒杀价锁定，B 商品参与满减
即使后面有 VIP 折扣，A 商品也不会再打折

这样拆分之后，电商里的几乎所有优惠场景都能归到这三类模式之一，只需要在引擎里 setMode() 一下，就能决定计算方式。

怎么用？

安装方式很简单：

composer require hejunjie/promotion-engine

然后可以直接写：

use Hejunjie\PromotionEngine\PromotionEngine;
use Hejunjie\PromotionEngine\Rules\FullReductionRule;
use Hejunjie\PromotionEngine\Rules\VipDiscountRule;
use Hejunjie\PromotionEngine\Models\Cart;
use Hejunjie\PromotionEngine\Models\User;

// 创建一个购物车模型，实际场景中使用需要计算商品的名称/价格/购买数量执行即可
// 可以通过第四个参数来设置标签，执行规则时可以设置需要执行的标签，标签支持设置多个
$cart = new Cart();
$cart->addItem('T恤', 120, 1, ['tag']);
$cart->addItem('牛仔裤', 150, 1, ['tag','promo']);

// 创建一个用户模型，实际场景中仅是用来区分用户是否可以享受关于VIP折扣方面的规则
// 如果没有设置VIP折扣方面的规则，则不会影响任何数据
$user = new User(vip: true);

$engine = new PromotionEngine();
$engine->setMode('sequential'); // 选择折上折模式
$engine->addRule(new Rules\FullReductionRule(100, 30, ['promo'], 1)); // 满 200 减 50, 仅适用于有 promo 标签的商品, 执行顺序 1（数字越小越先执行）
$engine->addRule(new Rules\VipDiscountRule(0.9, ['tag'], 2));      // VIP 9 折, 仅适用于有 tag 标签的商品, 执行顺序 2（数字越小越先执行）

$result = $engine->calculate($cart, $user);

print_r(json_encode($result, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE));

你会得到类似这样的结果：

{
    "original": 270,
    "discount": 54,
    "final": 216,
    "details": [
        "指定商品满100减30 (-¥30)",
        "VIP 0.9 折 (-¥24)"
    ],
    "items": [
        {
            "name": "T恤",
            "price": 108,
            "qty": 1,
            "tags": [
                "tag"
            ],
            "original_price": 120,
            "locked": false
        },
        {
            "name": "牛仔裤",
            "price": 108,
            "qty": 1,
            "tags": [
                "tag",
                "promo"
            ],
            "original_price": 150,
            "locked": false
        }
    ]
}

这个库能带来什么？

代码更干净：不用每次都写一堆 if/else，逻辑集中在「规则类」里。
模式可切换：想独立算就 independent，想折上折就 sequential，换个模式就行。
扩展方便：有新活动？直接加个规则类，比如「第 N 件打折」「阶梯满减」，不用动核心逻辑。

最后

这个库不是大而全的框架，就是一个我在工作中常用到的小工具，我把它整理出来放到 GitHub 上，希望以后别的项目也能用得上，也欢迎你们试试看。

GitHub 地址在这里：https://github.com/zxc7563598/php-promotion-engine

如果你有建议、发现了 bug，或者有好玩的规则想加进来，欢迎 PR。

收费跑路的私服玩腻了？2025最新自建DNF单机教程，重回60版本阿拉德！

Fri, 25 Jul 2025 02:15:56 GMT

前段时间突然想回忆下小时候玩 DNF 的感觉，牛头巨兽、僵尸王、光之城主、悬空城。就连技能都要数着技能点算这个点几级那个点不点。

现在的 DNF 说实话，版本太快了、剧情感觉已经从当年的乡村武侠进步到银河战争了，也不是说这样不好，但是总感觉当年的味道已经完全找不到了

想着要不玩个私服吧，结果一圈找下来——不是太卡就是太坑，不是要冲钱开会员就是干脆跑路关服。关键是我不是真的图啥竞技氛围，我就想一个人刷刷图，体验一下当年那个60版本的感觉。

后来一咬牙：干脆自己搞一个单机版得了！

为什么要自己搭一个？

说白了就一句话：

不想被人掐着玩，我想啥时候玩就啥时候玩。

而且自己搭在自己机器上，不用担心服务器关服，不用看别人脸色，也不用氪金，数据也不会莫名其妙丢了。最重要的是，自己能控制一切，有种自己拥有整个阿拉德的感觉。

那这些私服都是从哪来的？

这事其实挺有意思的。

当年台服 DNF 关服后，服务器端的代码不知道怎么就流出来了，后来就被各路大神研究魔改，从那之后才慢慢有了各种私服、单机端。你现在在网上能找到的服务端，基本都是在这堆源码基础上改出来的。

不过不管怎么改，底层运行环境其实差不多，你需要一台可以跑32位程序的 CentOS 7 系统，不然不是装不上就是运行报错。

可以在自己的电脑上跑虚拟机，也可以从类似「阿里云」一类的云服务商购买服务器，一般我会更愿意开一台云服务器，因为服务端跑在自己的电脑上也是有性能消耗的，并且在自己的电脑上跑就绑死自己的电脑了，放在云服务器上，客户端放U盘，不管在什么地方，拿过一台电脑都不耽误我继续玩

搭建之前，先说点背景

折腾 DNF 单机其实就两部分：服务端 和 客户端。

服务端 👉 就是“服务器核心”，管副本逻辑、爆装掉落等等。
客户端 👉 你平时打开玩的那个游戏程序。

现在网上资源很多，像千山、夜白这些作者都提供了现成的服务端和配套客户端，基本上在 DNF 台服吧 就能找到，搜一搜「DNF 千山」这种关键词，资料一大把。
（资源这里就不贴了，大家自己搜会更灵活）

这些资源就是最基础的一套“底板”：
有了它，游戏能跑；想玩什么版本，就在这个底板上动手脚。

PVF 文件：决定游戏“长什么样”

在 DNF 的圈子里，你会经常听到“PVF”这个词。

PVF 就是游戏的版本文件——它定义了副本、职业、装备等各种内容。
你想体验 60 版本，就换 60 版本的 PVF；想试试后面出的职业，换个新 PVF 就能跑出来。

通常，换 PVF 还会带上：

NPK 文件：不同版本的图片、美术资源（怪物、装备、UI…）
DLL 文件：控制一些游戏逻辑，比如最高等级上限

所以简单说，想换游戏内容 = 换 PVF + 对应资源。

df_game_r 文件：服务端的心脏

另一个关键文件就是 df_game_r。

它是 DNF 服务端的核心进程文件，游戏所有的逻辑都靠它跑；
本质上它也决定了游戏版本和一些内容，客户端连上的就是它。

重点是：df_game_r 是一个 32 位程序。
这意味着环境要求比较苛刻——必须装齐一堆 .i686 库、搞对 /lib 里的链接，不然启动就会直接报错。

现在很多人搭建不成功，其实不是服务端有问题，而是 环境翻车：缺库、版本不对、链接没配好。
所以我建议——保险起见，搭建前先把所有库更新一遍，少踩坑。

建议用 CentOS 7.9（64位）

为什么推荐这个版本？因为：

它比较稳定
各种库版本兼容性最好
是 CentOS 7 的最后一个官方版本，不容易出幺蛾子

记住一句话：CentOS 7.9 + 支持32位库，能跑基本就稳了。

那我是怎么装的？

不管你是用的什么版本去部署的服务端、有一些版本没问题可以直接跑起来的那自然是最好的，直接畅玩，但是大部分人可能并不会有这种好运气，因此如果出现了问题，我会建议把应该装的库都重新处理一下

以下是在所谓的服务端部署完成，服务器重启完成后再去执行的

这么做是因为如果提前装好扩展，有些一键包会清理掉已经装好的扩展，导致出现异常

准备工作先来一套：

sudo curl -o /etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/Centos-7.repo

换成阿里云的源（有些键包会清理掉yum源，导致下载扩展失败）

sudo yum clean all
sudo yum makecache
sudo yum update -y
sudo yum install -y epel-release
sudo yum groupinstall -y "Development Tools"

清空缓存、更新现有库

然后装一堆基础库（64位+32位一块上）：

sudo yum install -y \
  glibc glibc-devel glibc.i686 glibc-devel.i686 \
  libstdc++ libstdc++-devel libstdc++.i686 libstdc++-devel.i686 \
  zlib zlib-devel zlib.i686 zlib-devel.i686 \
  ncurses ncurses-devel ncurses.i686 ncurses-devel.i686 \
  freetype freetype.i686 freetype-devel freetype-devel.i686 \
  libX11 libX11.i686 libX11-devel libX11-devel.i686 \
  libXext libXext.i686 libXext-devel libXext-devel.i686 \
  libXrender libXrender.i686 libXrender-devel libXrender-devel.i686 \
  openssl openssl-devel \
  readline readline-devel \
  pcre pcre-devel

关键的软链接操作（不然很多老程序找不到东西）

sudo ln -sf /usr/lib/ld-2.17.so /lib/ld-linux.so.2
sudo ln -sf /usr/lib64/libstdc++.so.6 /usr/lib/libstdc++.so.6

再把这俩路径加进 ld.so 里：

echo "/lib" | sudo tee /etc/ld.so.conf.d/lib.conf
echo "/lib64" | sudo tee /etc/ld.so.conf.d/lib64.conf
sudo ldconfig

设置下环境变量（部分脚本会依赖）

export LD_LIBRARY_PATH=/lib:/usr/lib:/lib64:/usr/lib64

检查下装得正不正常

rpm -qa | grep -E 'glibc|libstdc++|zlib|freetype|ncurses|libX11|libXext|libXrender' | sort

ls -l /lib/ld-linux.so.2

应该输出：/lib/ld-linux.so.2 -> /usr/lib/ld-2.17.so

file /usr/lib/libstdc++.so.6 || file /usr/lib64/libstdc++.so.6

应该输出：/usr/lib/libstdc++.so.6: symbolic link to `libstdc++.so.6.0.19'

ldd --version

应该输出：ldd (GNU libc) 2.17 Copyright (C) 2012 Free Software Foundation, Inc. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 由 Roland McGrath 和 Ulrich Drepper 编写。

接下来就可以去进行不同的版本需要你去做的事情了

启动前最后一步：跑起来之前，别忘了这几件小事

环境、库都折腾好了，真正启动服务之前，还得在 /home/neople/game 目录（大部分服务端都是这里，不在这里的服务端，安装时一般会特别说明）先做三件事：

1️⃣ 加入或替换 df_game_r
👉 这个文件决定了游戏跑的是哪个版本，几乎所有一键包都会自带或者提供下载链接。换了它，就等于换了“游戏内核”。

2️⃣ 加入或替换 Script.pvf
👉 这是游戏内容的大脑，职业数值、副本逻辑全靠它。有些魔改大佬就是改 PVF 来加东西（比如新职业、变态装备），网上的资源也一大把。

3️⃣ 加入或替换 publickey.pem
👉 这是客户端和服务端互相“认身份”的凭证。客户端目录里都有，只要服务端和客户端用的 publickey.pem 一致，客户端才能正常连上服务端。

🔧 这三件事做完，再去执行对应一键包的启动命令（一般是 /root 目录下的 ./run）

最后等个几分钟十几分钟的，直到看到这样的信息

GeoIP Allow Country Code : CN
GeoIP Allow Country Code : HK
GeoIP Allow Country Code : KR
GeoIP Allow Country Code : MO
GeoIP Allow Country Code : TW

就能顺利开服了，也就是大家常说的「跑五国」

客户端这边也别忘了改 IP

客户端目录里通常会有 game.ini 和 dnf.toml 这两个文件，都能用记事本打开。
把里面的服务器 IP 改成你自己服务器的地址，保存。

这样客户端才能连上你自己的服务端。

最后

写这个也不是想教大家怎么玩服务器，纯粹就是分享一下我的折腾经历，毕竟我查了好久中文资料，大多都讲得不明不白。要不是踩了几个坑，我可能也不想自己写了。

如果你也跟我一样，想再体验一次当年的 DNF，那真不妨动手试试。

私服再多，不如自己动手。数据、节奏、体验，全都在你掌控中。

如果你觉得有用，点个赞或者收藏下吧。
也欢迎来评论区交流搭建时遇到的问题，我能帮的都会帮 👍

用 GitHub Issues 做任务管理和任务 List，简单好用！

Mon, 23 Jun 2025 03:59:37 GMT

说实话，我平时也是一个人写代码，每次开完会整理任务最麻烦：

一堆事项堆在聊天里、文档里，或者散落在邮件里……

为了理清这些，我通常会做一份 List，标好优先级，再安排到每日的工作里

虽然这个办法能解决大部分问题

但说实在的：

一是整理 List 本身就需要时间

二是每完成一件事，还得回到 List 去勾掉已完成的任务 让人感觉并没有那么顺手、痛快

于是，我也一直在想： 有没有更好的办法，更自然地安排和管理任务呢？

我是怎么想到用 Issue 模板的

其实 GitHub Issues 我们都见过，也都用过。
但默认的 Issues 创建体验其实比较简单，也没什么结构化管理。

后来看了一些大项目，发现他们都有自己的 Issue 模板，让提交 Issue 的人：

✅ 按结构化字段提供信息
✅ 自动附加 Labels
✅ 简单一看就明白这个 Issue 是干什么的

我就想：「那我自己的小仓库，能不能也搞一套？就算是一个人的项目，也能更有秩序。」
结果发现，还真很好用！

用途示例：Issue 模板让事务更有结构

现在，我是这么做的：

用 Issue 模板管理自己的任务。
把 Issue 当成小型看板。
用 Labels 标记状态（pending、in progress、review、done）。
完成代码后，在 PR 描述里写 fixes #xxx，合并后 Issue 就自动关闭。

这个简单的小改造，让我：
✅ 没有因为漏掉任务而后悔过
✅ 完成和提交之间有记录和参考
✅ 即使过很久，也能快速回顾历史

更好的是，因为可以分配负责人Assignee，因此在团队协作中，通过这种方案，可以非常便捷的将各个需要处理的任务拆分之后分配给不同的成员负责

成员可以直接根据 Issue 来工作，完成工作后提交即可，在审计通过后任务则会自动关闭 Issue ，整个流程非常丝滑

怎么配置 Issue 模板

其实配置 Issue 模板没有什么复杂，就是在 仓库根目录/.github/ISSUE_TEMPLATE 文件夹中创建 .yml 文件。

目录不存在可以自行创建

对于 .yml 文件的命名没有要求，GitHub会解析 config.yml 作为配置文件，其余所有 .yml 文件均视作 Issue 模板

config.yml 配置说明

blank_issues_enabled: false
contact_links:
  - name: 📌 功能建议提交说明
    url: https://example.com/docs/issues
    about: 在提交 Issue 之前，请先阅读提交流程说明。
  - name: ❓ 问答社区
    url: https://example.com/discussions
    about: 有疑问？先来社区讨论。

|字段|用途| | ------| -------------------------------------| |blank_issues_enabled|是否允许提交非模板的 Issue| |contact_links|为提交 Issue 的页面提供额外链接|

Issue 模板配置文件简单示例：

name: 🐞 Bug 报告
description: 用于提交 bug 报告
title: "[Bug]: "
labels: ["bug", "pending"]

body:
  - type: input
    id: title
    attributes:
      label: 问题标题
      placeholder: 简单概括问题
    validations:
      required: true
  - type: textarea
    id: details
    attributes:
      label: 问题描述
      description: 请附上堆栈、截图或参考代码片段
    validations:
      required: true

Issue 模板 YML 可用字段一览

|字段|用途|示例| | ------| -------------------------------------| ------------| |name|模板显示的名字|name: 🐞 Bug 报告| |description|模板显示的描述|description: 用于提交 bug 报告| |title|创建 Issue 时自动填充的标题|title: "[Bug]: "| |labels|创建 Issue 自动附加的 Label 列表|labels: ["bug", "pending"]| |assignees|创建 Issue 自动指定的负责人|assignees: ["user1", "user2"]| |body|模板主体区域，里面是字段配置数组|见下文示例| |body.type|字段类型：input、textarea、dropdown、checkboxes、markdown|type: input| |body.id|唯一标识字段 ID，用于引用值|id: description| |body.attributes.label|在 Issue 创建页面显示的字段标题|label: 问题描述| |body.attributes.description|在 Issue 创建页面显示的字段说明|description: 请详细描述...| |body.attributes.placeholder|在 Issue 创建页面显示的默认值或示例|placeholder: 在这里写错误日志...| |body.attributes.options|可选项列表，仅对dropdown、checkboxes类型有效|options: ["选项1", "选项2"]| |body.validations.required|是否为必填字段 (true/false)|required: true|

可用的字段类型

|类型|用途| | ------| --------------------------------------------------------| |markdown|只展示一段 Markdown 内容，不可编辑，适合作为提示、说明| |input|单行文本字段，适合填写标题、URL、单行参数等| |textarea|多行文本字段，适合错误日志、堆栈、代码片段| |dropdown|可选下拉框，适合确定性选项（如操作系统类型、环境类型）| |checkboxes|多选框，适合提供多个选项让提交者勾选|

我自己的配置示例

我也整理了一套自己的 Issue 模板，用于：

✅ 问题提问
✅ 合作／雇佣邀请
✅ bug 报告
✅ 需求排期

👉 我放在自己的个人仓库里，大家感兴趣可以参考：点击查看

简而言之

说实话，GitHub Issues 模板对我这种个人开发者，也能带来很大好处：

更清晰的任务结构。
完成和提交之间有标准化记录。
即使过很久，也能快速回顾。

如果你也是一个平时单兵作战、但想让自己的工作更有结构的人，建议你也可以尝试配置一套 Issue 模板。
它不会让你额外麻烦，反而让后续一切更简单。

用 WakaTime + GitHub Actions 打造属于你的个性化 GitHub 主页

Mon, 23 Jun 2025 03:59:37 GMT

在技术人眼里，GitHub 不只是代码仓库，它也是你的技术简历、作品展厅，甚至是你在互联网上的“第二张名片”。

而今天，我们就来聊聊：如何从零开始，打造一个自动更新、内容丰富、有个性、还能展示技术实力的 GitHub 主页。

先贴一张我的 GitHub 个人页面，你也可以直接打开我的 GitHub 主页查看：点击查看

🏠 从一个特殊的仓库开始：GitHub 主页原理

GitHub 提供了一个非常简洁的展示方式：只要你创建一个和自己用户名相同的仓库，README 就会展示在你个人主页顶部。

比如我叫 zxc7563598，那我就新建一个仓库叫：

zxc7563598/zxc7563598

这个仓库的 README.md，就是你在 GitHub 首页展示的内容。你可以在里面写个人介绍、技能栈、项目链接，甚至放个代码统计图表。

技术人自己的「About Me」，从这里开始。

⌛ 加一点数据味道：使用 WakaTime 统计代码时间

如果你希望展示的不只是“看起来厉害”，而是“我真的在持续写代码”，那么推荐你使用 WakaTime ——一个开发者专用的时间追踪工具。

它支持 VSCode / JetBrains / Vim / 甚至 Eclipse，安装插件、填入 API Key 后，它就能悄悄记录你每天写了哪些语言、用了多长时间。

你得到的是一份“编程时间日报”，而不是模糊的「我最近在忙项目」。

为了使用它，你需要完成下面这些事情：

前往 wakatime.com 并创建一个帐户。
从 WakaTime 中的帐户设置中获取 WakaTime API 密钥。
在您最喜欢的编辑器/IDE 中安装 WakaTime 插件。官网都有非常完善的教程。
粘贴您的 API 密钥以开始分析。

🔁 自动更新：用 GitHub Actions 每天写入统计数据

有了 WakaTime 数据，还得展示在主页上。

我们可以借助开源项目 athul/waka-readme，通过 GitHub Actions 每天自动将你最新的 WakaTime 统计写入 README.md。

具体操作方法如下：

创建一个 GitHub Token，并授予 repo 权限。

如果你不知道从哪里设置 GitHub Token 可以直接从这个链接进入并进行设置点击查看

在你的仓库中创建一个名为 .github/workflows/waka.yml 的文件，并添加以下内容：

 name: Waka Readme

 on:
 schedule:
     - cron: '0 16 * * *'
 workflow_dispatch:
 jobs:
 update-readme:
     name: Update Readme with Metrics
     runs-on: ubuntu-latest
     steps:
     - uses: anmol098/waka-readme-stats@master
         with:
         WAKATIME_API_KEY: ${{ secrets.WAKATIME_API_KEY }}
         GH_TOKEN: ${{ secrets.GH_TOKEN }}
         LOCALE: zh

设置 WAKATIME_API_KEY 和 GH_TOKEN 在仓库的 Settings -> Secrets and variables -> Actions -> New repository secret 中添加 WAKATIME_API_KEY 和 GH_TOKEN 两个密钥。

这里的 WAKATIME_API_KEY 就是你之前获取的 WakaTime API 密钥，GH_TOKEN 就是你之前创建的 GitHub Token。
在 README.md 中你想要添加统计的位置添加以下代码：
```
 
 
```
至此，所有的配置就都已经完成了，GitHub Actions 会在北京时间 00:00 自动执行，并将该段代码替换为 WakaTime 的统计数据

你也可以手动执行，在仓库的 Actions 中点击 Waka Readme，然后点击 Run workflow 按钮即可立即手动执行

🎁 最后：别让主页变成“Hello World”

很多开发者注册 GitHub 后就再也没碰过个人主页，但其实这里是你展现专业度与热情的一个绝佳窗口。

不管你是找工作、做开源、还是纯粹想留下点印记，都值得花一两个小时，搭建一个属于你的主页。

项目代码会说话，你的主页也一样。

私有网络与服务端通信配置记录

Fri, 13 Jun 2025 08:52:45 GMT

背景介绍：

在国内直接访问境外网站常受限制，原因在于国内对境外流量进行了严格控制。
但有一个特点：国内到港澳台之间是互通的。
也就是说，你可以买一台最便宜的香港服务器作为“中转”，因为：

国内 -> 香港之间速度极快，延迟极低。

香港 -> 境外的连接没有封锁。

比如，阿里云香港机器，1 元 / 1GB 流量，完全够用，性价比极高，且不限速。
用 Shadowsocks 做一层简单转发，配合 Clash 客户端，完全可以跑满带宽。

简而言之：
用一台香港服务器当“跳板”，国内到香港不限速，香港再帮你访问境外。

接下来是完整配置步骤。

一、在服务器上安装 Shadowsocks 服务端

推荐使用官方维护的 shadowsocks-libev，因为简单、稳定、性能好。

更新软件源

sudo apt update

安装 Shadowsocks

sudo apt install shadowsocks-libev

二、配置 Shadowsocks 服务

配置文件默认放在：

/etc/shadowsocks-libev/config.json

修改配置：

sudo vim /etc/shadowsocks-libev/config.json

修改为：

{
    "server": "0.0.0.0",
    "mode": "tcp_and_udp",
    "server_port": 8388,
    "local_port": 1080,
    "password": "随便起一个密码",
    "timeout": 86400,
    "method": "chacha20-ietf-poly1305"
}

关键参数说明：

server: 0.0.0.0 表示监听所有网卡。

server_port: 修改为你需要的端口。

password: 修改为自己的密码。

method: 可选 chacha20-ietf-poly1305、aes-256-gcm 等。

mode: 通常为 tcp_and_udp，使 UDP 可用。

三、启动和管理

启动服务：

sudo systemctl restart shadowsocks-libev.service

检查状态：

sudo systemctl status shadowsocks-libev.service

配置开机自动启动：

sudo systemctl enable shadowsocks-libev.service

四、检查是否正常

在服务器上检查端口是否在监听：

ss -tulpn | grep ss-server

如果正常，会显示 ss-server 在监听配置好的端口。

在客户端检查连接：
修改 Clash 节点：

- name: "我的服务器"
  type: ss
  server: 服务器IP
  port: 8388
  cipher: chacha20-ietf-poly1305
  password: "设置好的密码"
  udp: false

五、附加建议

配置防火墙

允许相应端口：

sudo ufw allow 8388/tcp
sudo ufw allow 8388/udp

检查日志

journalctl -u shadowsocks-libev.service -f

六、客户端配置参考链接

Windows 客户端：Clash for Windows

iOS 客户端：Shadowrocket

Android 客户端：Clash for Android

Mac 客户端：Clash Verge

七、配置参考

Clash 完整配置规则

port: 7890
socks-port: 7891
redir-port: 7892
allow-lan: false
mode: Rule
log-level: info
external-controller: 127.0.0.1:9090
secret: ""
cfw-bypass:
  - localhost
  - 127.*
  - 10.*
  - 172.16.*
  - 172.17.*
  - 172.18.*
  - 172.19.*
  - 172.20.*
  - 172.21.*
  - 172.22.*
  - 172.23.*
  - 172.24.*
  - 172.25.*
  - 172.26.*
  - 172.27.*
  - 172.28.*
  - 172.29.*
  - 172.30.*
  - 172.31.*
  - 192.168.*
  - <local>
cfw-latency-timeout: 3000
proxies:
  - name: "我的服务器"
    type: ss
    server: 服务器IP
    port: 8388
    cipher: chacha20-ietf-poly1305
    password: "设置好的密码"
    udp: false
proxy-groups:
  - name: CroLAX
    type: select
    proxies:
      - "HongKong-Proxy"
      - "DIRECT"
rules:
  - DOMAIN,hls.itunes.apple.com,CroLAX
  - DOMAIN,itunes.apple.com,CroLAX
  - DOMAIN,itunes.com,CroLAX
  - DOMAIN-SUFFIX,icloud.com,DIRECT
  - DOMAIN-SUFFIX,icloud-content.com,DIRECT
  - DOMAIN-SUFFIX,me.com,DIRECT
  - DOMAIN-SUFFIX,mzstatic.com,DIRECT
  - DOMAIN-SUFFIX,aaplimg.com,DIRECT
  - DOMAIN-SUFFIX,cdn-apple.com,DIRECT
  - DOMAIN-SUFFIX,apple.com,DIRECT
  ## 国内网站
  - DOMAIN-SUFFIX,akadns.net,DIRECT
  - DOMAIN-SUFFIX,akamaized.net,DIRECT
  - DOMAIN-SUFFIX,cn,DIRECT
  - DOMAIN-KEYWORD,-cn,DIRECT
  - DOMAIN-SUFFIX,126.com,DIRECT
  - DOMAIN-SUFFIX,126.net,DIRECT
  - DOMAIN-SUFFIX,127.net,DIRECT
  - DOMAIN-SUFFIX,163.com,DIRECT
  - DOMAIN-SUFFIX,360buyimg.com,DIRECT
  - DOMAIN-SUFFIX,36kr.com,DIRECT
  - DOMAIN-SUFFIX,acfun.tv,DIRECT
  - DOMAIN-SUFFIX,air-matters.com,DIRECT
  - DOMAIN-SUFFIX,aixifan.com,DIRECT
  - DOMAIN-KEYWORD,alicdn,DIRECT
  - DOMAIN-KEYWORD,alipay,DIRECT
  - DOMAIN-KEYWORD,taobao,DIRECT
  - DOMAIN-SUFFIX,amap.com,DIRECT
  - DOMAIN-SUFFIX,autonavi.com,DIRECT
  - DOMAIN-KEYWORD,baidu,DIRECT
  - DOMAIN-SUFFIX,bdimg.com,DIRECT
  - DOMAIN-SUFFIX,bdstatic.com,DIRECT
  - DOMAIN-SUFFIX,bilibili.com,DIRECT
  - DOMAIN-SUFFIX,caiyunapp.com,DIRECT
  - DOMAIN-SUFFIX,clouddn.com,DIRECT
  - DOMAIN-SUFFIX,cnbeta.com,DIRECT
  - DOMAIN-SUFFIX,cnbetacdn.com,DIRECT
  - DOMAIN-SUFFIX,cootekservice.com,DIRECT
  - DOMAIN-SUFFIX,csdn.net,DIRECT
  - DOMAIN-SUFFIX,ctrip.com,DIRECT
  - DOMAIN-SUFFIX,dgtle.com,DIRECT
  - DOMAIN-SUFFIX,dianping.com,DIRECT
  - DOMAIN-SUFFIX,douban.com,DIRECT
  - DOMAIN-SUFFIX,doubanio.com,DIRECT
  - DOMAIN-SUFFIX,duokan.com,DIRECT
  - DOMAIN-SUFFIX,easou.com,DIRECT
  - DOMAIN-SUFFIX,ele.me,DIRECT
  - DOMAIN-SUFFIX,feng.com,DIRECT
  - DOMAIN-SUFFIX,fir.im,DIRECT
  - DOMAIN-SUFFIX,frdic.com,DIRECT
  - DOMAIN-SUFFIX,g-cores.com,DIRECT
  - DOMAIN-SUFFIX,godic.net,DIRECT
  - DOMAIN-SUFFIX,gtimg.com,DIRECT
  - DOMAIN-SUFFIX,hongxiu.com,DIRECT
  - DOMAIN-SUFFIX,hxcdn.net,DIRECT
  - DOMAIN-SUFFIX,iciba.com,DIRECT
  - DOMAIN-SUFFIX,ifeng.com,DIRECT
  - DOMAIN-SUFFIX,ifengimg.com,DIRECT
  - DOMAIN-SUFFIX,ipip.net,DIRECT
  - DOMAIN-SUFFIX,iqiyi.com,DIRECT
  - DOMAIN-SUFFIX,jd.com,DIRECT
  - DOMAIN-SUFFIX,jianshu.com,DIRECT
  - DOMAIN-SUFFIX,knewone.com,DIRECT
  - DOMAIN-SUFFIX,le.com,DIRECT
  - DOMAIN-SUFFIX,lecloud.com,DIRECT
  - DOMAIN-SUFFIX,lemicp.com,DIRECT
  - DOMAIN-SUFFIX,licdn.com,DIRECT
  - DOMAIN-SUFFIX,luoo.net,DIRECT
  - DOMAIN-SUFFIX,meituan.com,DIRECT
  - DOMAIN-SUFFIX,meituan.net,DIRECT
  - DOMAIN-SUFFIX,mi.com,DIRECT
  - DOMAIN-SUFFIX,miaopai.com,DIRECT
  - DOMAIN-SUFFIX,microsoft.com,DIRECT
  - DOMAIN-SUFFIX,microsoftonline.com,DIRECT
  - DOMAIN-SUFFIX,miui.com,DIRECT
  - DOMAIN-SUFFIX,miwifi.com,DIRECT
  - DOMAIN-SUFFIX,mob.com,DIRECT
  - DOMAIN-SUFFIX,netease.com,DIRECT
  - DOMAIN-SUFFIX,office.com,DIRECT
  - DOMAIN-KEYWORD,officecdn,DIRECT
  - DOMAIN-SUFFIX,office365.com,DIRECT
  - DOMAIN-SUFFIX,oschina.net,DIRECT
  - DOMAIN-SUFFIX,ppsimg.com,DIRECT
  - DOMAIN-SUFFIX,pstatp.com,DIRECT
  - DOMAIN-SUFFIX,qcloud.com,DIRECT
  - DOMAIN-SUFFIX,qdaily.com,DIRECT
  - DOMAIN-SUFFIX,qdmm.com,DIRECT
  - DOMAIN-SUFFIX,qhimg.com,DIRECT
  - DOMAIN-SUFFIX,qhres.com,DIRECT
  - DOMAIN-SUFFIX,qidian.com,DIRECT
  - DOMAIN-SUFFIX,qihucdn.com,DIRECT
  - DOMAIN-SUFFIX,qiniu.com,DIRECT
  - DOMAIN-SUFFIX,qiniucdn.com,DIRECT
  - DOMAIN-SUFFIX,qiyipic.com,DIRECT
  - DOMAIN-SUFFIX,qq.com,DIRECT
  - DOMAIN-SUFFIX,qqurl.com,DIRECT
  - DOMAIN-SUFFIX,rarbg.to,DIRECT
  - DOMAIN-SUFFIX,ruguoapp.com,DIRECT
  - DOMAIN-SUFFIX,segmentfault.com,DIRECT
  - DOMAIN-SUFFIX,sinaapp.com,DIRECT
  - DOMAIN-SUFFIX,smzdm.com,DIRECT
  - DOMAIN-SUFFIX,sogou.com,DIRECT
  - DOMAIN-SUFFIX,sogoucdn.com,DIRECT
  - DOMAIN-SUFFIX,sohu.com,DIRECT
  - DOMAIN-SUFFIX,soku.com,DIRECT
  - DOMAIN-SUFFIX,speedtest.net,DIRECT
  - DOMAIN-SUFFIX,sspai.com,DIRECT
  - DOMAIN-SUFFIX,suning.com,DIRECT
  - DOMAIN-SUFFIX,taobao.com,DIRECT
  - DOMAIN-SUFFIX,tencent.com,DIRECT
  - DOMAIN-SUFFIX,tenpay.com,DIRECT
  - DOMAIN-SUFFIX,tianyancha.com,DIRECT
  - DOMAIN-SUFFIX,tmall.com,DIRECT
  - DOMAIN-SUFFIX,tudou.com,DIRECT
  - DOMAIN-SUFFIX,umetrip.com,DIRECT
  - DOMAIN-SUFFIX,upaiyun.com,DIRECT
  - DOMAIN-SUFFIX,upyun.com,DIRECT
  - DOMAIN-SUFFIX,veryzhun.com,DIRECT
  - DOMAIN-SUFFIX,weather.com,DIRECT
  - DOMAIN-SUFFIX,weibo.com,DIRECT
  - DOMAIN-SUFFIX,xiami.com,DIRECT
  - DOMAIN-SUFFIX,xiami.net,DIRECT
  - DOMAIN-SUFFIX,xiaomicp.com,DIRECT
  - DOMAIN-SUFFIX,ximalaya.com,DIRECT
  - DOMAIN-SUFFIX,xmcdn.com,DIRECT
  - DOMAIN-SUFFIX,xunlei.com,DIRECT
  - DOMAIN-SUFFIX,yhd.com,DIRECT
  - DOMAIN-SUFFIX,yihaodianimg.com,DIRECT
  - DOMAIN-SUFFIX,yinxiang.com,DIRECT
  - DOMAIN-SUFFIX,ykimg.com,DIRECT
  - DOMAIN-SUFFIX,youdao.com,DIRECT
  - DOMAIN-SUFFIX,youku.com,DIRECT
  - DOMAIN-SUFFIX,zealer.com,DIRECT
  - DOMAIN-SUFFIX,zhihu.com,DIRECT
  - DOMAIN-SUFFIX,zhimg.com,DIRECT
  - DOMAIN-SUFFIX,zimuzu.tv,DIRECT
  - DOMAIN-KEYWORD,netflix,CroLAX
  - DOMAIN-KEYWORD,nflx,CroLAX
  ## 抗 DNS 污染
  - DOMAIN-KEYWORD,amazon,CroLAX
  - DOMAIN-KEYWORD,google,CroLAX
  - DOMAIN-KEYWORD,gmail,CroLAX
  - DOMAIN-KEYWORD,youtube,CroLAX
  - DOMAIN-KEYWORD,facebook,CroLAX
  - DOMAIN-SUFFIX,fb.me,CroLAX
  - DOMAIN-SUFFIX,fbcdn.net,CroLAX
  - DOMAIN-KEYWORD,twitter,CroLAX
  - DOMAIN-KEYWORD,instagram,CroLAX
  - DOMAIN-KEYWORD,dropbox,CroLAX
  - DOMAIN-SUFFIX,twimg.com,CroLAX
  - DOMAIN-KEYWORD,blogspot,CroLAX
  - DOMAIN-SUFFIX,youtu.be,CroLAX
  - DOMAIN-KEYWORD,whatsapp,CroLAX
  - DOMAIN-KEYWORD,googleapis,CroLAX
# Clubhouse
  - DOMAIN-SUFFIX,clubhouse.com,CroLAX
  - DOMAIN-SUFFIX,clubhouseapi.com,CroLAX
  - DOMAIN-SUFFIX,joinclubhouse.com,CroLAX
  - DOMAIN-SUFFIX,clubhouseprod.s3.amazonaws.com,CroLAX
  - DOMAIN-SUFFIX,clubhouse.pubnub.com,CroLAX

  - DOMAIN-SUFFIX, ap-oversea-tls.agora.io, DIRECT
  - DOMAIN-SUFFIX, ap-oversea.agora.io, DIRECT
  - DOMAIN-SUFFIX, ap-oversea2.agora.io, DIRECT
  - DOMAIN-SUFFIX, report-oversea.agora.io, DIRECT
  - IP-CIDR, 3.0.163.78/32, DIRECT
  - IP-CIDR, 13.230.60.35/32, DIRECT
  - IP-CIDR, 23.248.191.103/32, DIRECT
  - IP-CIDR, 23.248.191.105/32, DIRECT
  - IP-CIDR, 23.98.43.152/32, DIRECT
  - IP-CIDR, 35.178.208.187/32, DIRECT
  - IP-CIDR, 45.40.48.11/32, DIRECT
  - IP-CIDR, 45.255.124.98/32, DIRECT
  - IP-CIDR, 45.255.124.100/32, DIRECT
  - IP-CIDR, 45.255.124.101/32, DIRECT
  - IP-CIDR, 45.255.124.104/32, DIRECT
  - IP-CIDR, 45.255.124.105/32, DIRECT
  - IP-CIDR, 45.255.124.107/32, DIRECT
  - IP-CIDR, 45.255.124.108/32, DIRECT
  - IP-CIDR, 45.255.124.109/32, DIRECT
  - IP-CIDR, 45.255.124.135/32, DIRECT
  - IP-CIDR, 50.17.126.121/32, DIRECT
  - IP-CIDR, 52.52.84.170/32, DIRECT
  - IP-CIDR, 52.58.56.244/32, DIRECT
  - IP-CIDR, 52.194.158.59/32, DIRECT
  - IP-CIDR, 52.221.46.208/32, DIRECT
  - IP-CIDR, 54.178.26.110/32, DIRECT
  - IP-CIDR, 69.28.51.148/32, DIRECT
  - IP-CIDR, 103.59.49.10/32, DIRECT
  - IP-CIDR, 103.65.41.166/32, DIRECT
  - IP-CIDR, 103.65.41.169/32, DIRECT
  - IP-CIDR, 103.98.18.181/32, DIRECT
  - IP-CIDR, 103.98.18.183/32, DIRECT
  - IP-CIDR, 103.98.18.184/32, DIRECT
  - IP-CIDR, 103.98.18.189/32, DIRECT
  - IP-CIDR, 120.227.115.126/32, DIRECT
  - IP-CIDR, 122.10.255.165/32, DIRECT
  - IP-CIDR, 128.1.87.196/32, DIRECT
  - IP-CIDR, 129.227.71.203/32, DIRECT
  - IP-CIDR, 129.227.115.130/32, DIRECT
  - IP-CIDR, 148.153.126.146/32, DIRECT
  - IP-CIDR, 148.153.172.73/32, DIRECT
  - IP-CIDR, 148.153.172.74/32, DIRECT
  - IP-CIDR, 148.153.172.75/32, DIRECT
  - IP-CIDR, 148.153.172.76/32, DIRECT
  - IP-CIDR, 148.153.172.77/32, DIRECT
  - IP-CIDR, 164.52.0.244/32, DIRECT
  - IP-CIDR, 164.52.6.19/32, DIRECT
  - IP-CIDR, 164.52.6.21/32, DIRECT
  - IP-CIDR, 164.52.6.23/32, DIRECT
  - IP-CIDR, 164.52.6.24/32, DIRECT
  - IP-CIDR, 164.52.6.25/32, DIRECT
  - IP-CIDR, 164.52.32.57/32, DIRECT
  - IP-CIDR, 164.52.32.59/32, DIRECT
  - IP-CIDR, 164.52.32.60/32, DIRECT
  - IP-CIDR, 164.52.36.228/32, DIRECT
  - IP-CIDR, 164.52.36.232/32, DIRECT
  - IP-CIDR, 164.52.36.238/32, DIRECT
  - IP-CIDR, 164.52.36.243/32, DIRECT
  - IP-CIDR, 164.52.36.245/32, DIRECT
  - IP-CIDR, 164.52.36.254/32, DIRECT
  - IP-CIDR, 164.52.102.35/32, DIRECT
  - IP-CIDR, 164.52.102.66/32, DIRECT
  - IP-CIDR, 164.52.102.67/32, DIRECT
  - IP-CIDR, 164.52.102.68/32, DIRECT
  - IP-CIDR, 164.52.102.69/32, DIRECT
  - IP-CIDR, 164.52.102.70/32, DIRECT
  - IP-CIDR, 164.52.102.75/32, DIRECT
  - IP-CIDR, 164.52.102.76/32, DIRECT
  - IP-CIDR, 164.52.102.77/32, DIRECT
  - IP-CIDR, 164.52.102.91/32, DIRECT
  - IP-CIDR, 164.52.124.102/32, DIRECT
  - IP-CIDR, 199.190.44.36/32, DIRECT
  - IP-CIDR, 199.190.44.37/32, DIRECT
  - IP-CIDR, 202.181.136.106/32, DIRECT
  - IP-CIDR, 202.226.25.162/32, DIRECT
  - IP-CIDR, 202.226.25.166/32, DIRECT
  - IP-CIDR, 202.226.25.171/32, DIRECT
  - IP-CIDR, 202.226.25.195/32, DIRECT
  - IP-CIDR, 202.226.25.198/32, DIRECT
  - IP-CIDR, 129.227.57.143/32, DIRECT
  - IP-CIDR, 129.227.234.70/32, DIRECT
  - IP-CIDR, 129.227.234.82/32, DIRECT
  - IP-CIDR, 129.227.234.119/32, DIRECT
  - IP-CIDR, 129.227.71.144/32, DIRECT
  - IP-CIDR, 129.227.57.132/32, DIRECT
  - IP-CIDR, 129.227.57.134/32, DIRECT
  - IP-CIDR, 129.227.57.145/32, DIRECT
  - IP-CIDR, 129.227.71.141/32, DIRECT
  - IP-CIDR, 129.227.234.83/32, DIRECT
  - IP-CIDR, 129.227.71.142/32, DIRECT
  - IP-CIDR, 129.227.71.132/32, DIRECT
  - IP-CIDR, 129.227.71.133/32, DIRECT
  - IP-CIDR, 129.227.71.134/32, DIRECT
  - IP-CIDR, 129.227.234.67/32, DIRECT
  - IP-CIDR, 129.227.234.110/32, DIRECT
  - IP-CIDR, 129.227.234.112/32, DIRECT
  - IP-CIDR, 129.227.234.124/32, DIRECT
  - IP-CIDR, 129.227.71.140/32, DIRECT
  - IP-CIDR, 129.227.71.130/32, DIRECT
  - IP-CIDR, 129.227.71.131/32, DIRECT
  - IP-CIDR, 129.227.71.143/32, DIRECT
  - IP-CIDR, 129.227.156.17/32, DIRECT
  - IP-CIDR, 129.227.57.137/32, DIRECT
  - IP-CIDR, 129.227.156.20/32, DIRECT
  ## 国外网站
  - DOMAIN-SUFFIX,openai.com,CroLAX
  - DOMAIN-SUFFIX,9to5mac.com,CroLAX
  - DOMAIN-SUFFIX,abpchina.org,CroLAX
  - DOMAIN-SUFFIX,adblockplus.org,CroLAX
  - DOMAIN-SUFFIX,adobe.com,CroLAX
  - DOMAIN-SUFFIX,alfredapp.com,CroLAX
  - DOMAIN-SUFFIX,amplitude.com,CroLAX
  - DOMAIN-SUFFIX,ampproject.org,CroLAX
  - DOMAIN-SUFFIX,android.com,CroLAX
  - DOMAIN-SUFFIX,angularjs.org,CroLAX
  - DOMAIN-SUFFIX,aolcdn.com,CroLAX
  - DOMAIN-SUFFIX,apkpure.com,CroLAX
  - DOMAIN-SUFFIX,appledaily.com,CroLAX
  - DOMAIN-SUFFIX,appshopper.com,CroLAX
  - DOMAIN-SUFFIX,appspot.com,CroLAX
  - DOMAIN-SUFFIX,arcgis.com,CroLAX
  - DOMAIN-SUFFIX,archive.org,CroLAX
  - DOMAIN-SUFFIX,armorgames.com,CroLAX
  - DOMAIN-SUFFIX,aspnetcdn.com,CroLAX
  - DOMAIN-SUFFIX,att.com,CroLAX
  - DOMAIN-SUFFIX,awsstatic.com,CroLAX
  - DOMAIN-SUFFIX,azureedge.net,CroLAX
  - DOMAIN-SUFFIX,azurewebsites.net,CroLAX
  - DOMAIN-SUFFIX,bing.com,CroLAX
  - DOMAIN-SUFFIX,bintray.com,CroLAX
  - DOMAIN-SUFFIX,bit.com,CroLAX
  - DOMAIN-SUFFIX,bit.ly,CroLAX
  - DOMAIN-SUFFIX,bitbucket.org,CroLAX
  - DOMAIN-SUFFIX,bjango.com,CroLAX
  - DOMAIN-SUFFIX,bkrtx.com,CroLAX
  - DOMAIN-SUFFIX,blog.com,CroLAX
  - DOMAIN-SUFFIX,blogcdn.com,CroLAX
  - DOMAIN-SUFFIX,blogger.com,CroLAX
  - DOMAIN-SUFFIX,blogsmithmedia.com,CroLAX
  - DOMAIN-SUFFIX,blogspot.com,CroLAX
  - DOMAIN-SUFFIX,blogspot.hk,CroLAX
  - DOMAIN-SUFFIX,bloomberg.com,CroLAX
  - DOMAIN-SUFFIX,box.com,CroLAX
  - DOMAIN-SUFFIX,box.net,CroLAX
  - DOMAIN-SUFFIX,cachefly.net,CroLAX
  - DOMAIN-SUFFIX,chromium.org,CroLAX
  - DOMAIN-SUFFIX,cl.ly,CroLAX
  - DOMAIN-SUFFIX,cloudflare.com,CroLAX
  - DOMAIN-SUFFIX,cloudfront.net,CroLAX
  - DOMAIN-SUFFIX,cloudmagic.com,CroLAX
  - DOMAIN-SUFFIX,cmail19.com,CroLAX
  - DOMAIN-SUFFIX,cnet.com,CroLAX
  - DOMAIN-SUFFIX,cocoapods.org,CroLAX
  - DOMAIN-SUFFIX,comodoca.com,CroLAX
  - DOMAIN-SUFFIX,crashlytics.com,CroLAX
  - DOMAIN-SUFFIX,culturedcode.com,CroLAX
  - DOMAIN-SUFFIX,d.pr,CroLAX
  - DOMAIN-SUFFIX,danilo.to,CroLAX
  - DOMAIN-SUFFIX,dayone.me,CroLAX
  - DOMAIN-SUFFIX,db.tt,CroLAX
  - DOMAIN-SUFFIX,deskconnect.com,CroLAX
  - DOMAIN-SUFFIX,disq.us,CroLAX
  - DOMAIN-SUFFIX,disqus.com,CroLAX
  - DOMAIN-SUFFIX,disquscdn.com,CroLAX
  - DOMAIN-SUFFIX,dnsimple.com,CroLAX
  - DOMAIN-SUFFIX,docker.com,CroLAX
  - DOMAIN-SUFFIX,dribbble.com,CroLAX
  - DOMAIN-SUFFIX,droplr.com,CroLAX
  - DOMAIN-SUFFIX,duckduckgo.com,CroLAX
  - DOMAIN-SUFFIX,dueapp.com,CroLAX
  - DOMAIN-SUFFIX,dytt8.net,CroLAX
  - DOMAIN-SUFFIX,edgecastcdn.net,CroLAX
  - DOMAIN-SUFFIX,edgekey.net,CroLAX
  - DOMAIN-SUFFIX,edgesuite.net,CroLAX
  - DOMAIN-SUFFIX,engadget.com,CroLAX
  - DOMAIN-SUFFIX,entrust.net,CroLAX
  - DOMAIN-SUFFIX,eurekavpt.com,CroLAX
  - DOMAIN-SUFFIX,evernote.com,CroLAX
  - DOMAIN-SUFFIX,fabric.io,CroLAX
  - DOMAIN-SUFFIX,fast.com,CroLAX
  - DOMAIN-SUFFIX,fastly.net,CroLAX
  - DOMAIN-SUFFIX,fc2.com,CroLAX
  - DOMAIN-SUFFIX,feedburner.com,CroLAX
  - DOMAIN-SUFFIX,feedly.com,CroLAX
  - DOMAIN-SUFFIX,feedsportal.com,CroLAX
  - DOMAIN-SUFFIX,fiftythree.com,CroLAX
  - DOMAIN-SUFFIX,firebaseio.com,CroLAX
  - DOMAIN-SUFFIX,flexibits.com,CroLAX
  - DOMAIN-SUFFIX,flickr.com,CroLAX
  - DOMAIN-SUFFIX,flipboard.com,CroLAX
  - DOMAIN-SUFFIX,g.co,CroLAX
  - DOMAIN-SUFFIX,gabia.net,CroLAX
  - DOMAIN-SUFFIX,geni.us,CroLAX
  - DOMAIN-SUFFIX,gfx.ms,CroLAX
  - DOMAIN-SUFFIX,ggpht.com,CroLAX
  - DOMAIN-SUFFIX,ghostnoteapp.com,CroLAX
  - DOMAIN-SUFFIX,git.io,CroLAX
  - DOMAIN-KEYWORD,github,CroLAX
  - DOMAIN-KEYWORD,linkedin,CroLAX
  - DOMAIN-SUFFIX,globalsign.com,CroLAX
  - DOMAIN-SUFFIX,gmodules.com,CroLAX
  - DOMAIN-SUFFIX,godaddy.com,CroLAX
  - DOMAIN-SUFFIX,golang.org,CroLAX
  - DOMAIN-SUFFIX,gongm.in,CroLAX
  - DOMAIN-SUFFIX,goo.gl,CroLAX
  - DOMAIN-SUFFIX,goodreaders.com,CroLAX
  - DOMAIN-SUFFIX,goodreads.com,CroLAX
  - DOMAIN-SUFFIX,gravatar.com,CroLAX
  - DOMAIN-SUFFIX,gstatic.com,CroLAX
  - DOMAIN-SUFFIX,gvt0.com,CroLAX
  - DOMAIN-SUFFIX,hockeyapp.net,CroLAX
  - DOMAIN-SUFFIX,hotmail.com,CroLAX
  - DOMAIN-SUFFIX,icons8.com,CroLAX
  - DOMAIN-SUFFIX,ift.tt,CroLAX
  - DOMAIN-SUFFIX,ifttt.com,CroLAX
  - DOMAIN-SUFFIX,iherb.com,CroLAX
  - DOMAIN-SUFFIX,imageshack.us,CroLAX
  - DOMAIN-SUFFIX,img.ly,CroLAX
  - DOMAIN-SUFFIX,imgur.com,CroLAX
  - DOMAIN-SUFFIX,imore.com,CroLAX
  - DOMAIN-SUFFIX,instapaper.com,CroLAX
  - DOMAIN-SUFFIX,ipn.li,CroLAX
  - DOMAIN-SUFFIX,is.gd,CroLAX
  - DOMAIN-SUFFIX,issuu.com,CroLAX
  - DOMAIN-SUFFIX,itgonglun.com,CroLAX
  - DOMAIN-SUFFIX,itun.es,CroLAX
  - DOMAIN-SUFFIX,ixquick.com,CroLAX
  - DOMAIN-SUFFIX,j.mp,CroLAX
  - DOMAIN-SUFFIX,js.revsci.net,CroLAX
  - DOMAIN-SUFFIX,jshint.com,CroLAX
  - DOMAIN-SUFFIX,jtvnw.net,CroLAX
  - DOMAIN-SUFFIX,justgetflux.com,CroLAX
  - DOMAIN-SUFFIX,kat.cr,CroLAX
  - DOMAIN-SUFFIX,klip.me,CroLAX
  - DOMAIN-SUFFIX,libsyn.com,CroLAX
  - DOMAIN-SUFFIX,linode.com,CroLAX
  - DOMAIN-SUFFIX,lithium.com,CroLAX
  - DOMAIN-SUFFIX,littlehj.com,CroLAX
  - DOMAIN-SUFFIX,live.com,CroLAX
  - DOMAIN-SUFFIX,live.net,CroLAX
  - DOMAIN-SUFFIX,livefilestore.com,CroLAX
  - DOMAIN-SUFFIX,llnwd.net,CroLAX
  - DOMAIN-SUFFIX,macid.co,CroLAX
  - DOMAIN-SUFFIX,macromedia.com,CroLAX
  - DOMAIN-SUFFIX,macrumors.com,CroLAX
  - DOMAIN-SUFFIX,mashable.com,CroLAX
  - DOMAIN-SUFFIX,mathjax.org,CroLAX
  - DOMAIN-SUFFIX,medium.com,CroLAX
  - DOMAIN-SUFFIX,mega.co.nz,CroLAX
  - DOMAIN-SUFFIX,mega.nz,CroLAX
  - DOMAIN-SUFFIX,megaupload.com,CroLAX
  - DOMAIN-SUFFIX,microsofttranslator.com,CroLAX
  - DOMAIN-SUFFIX,mindnode.com,CroLAX
  - DOMAIN-SUFFIX,mobile01.com,CroLAX
  - DOMAIN-SUFFIX,modmyi.com,CroLAX
  - DOMAIN-SUFFIX,msedge.net,CroLAX
  - DOMAIN-SUFFIX,myfontastic.com,CroLAX
  - DOMAIN-SUFFIX,name.com,CroLAX
  - DOMAIN-SUFFIX,nextmedia.com,CroLAX
  - DOMAIN-SUFFIX,nsstatic.net,CroLAX
  - DOMAIN-SUFFIX,nssurge.com,CroLAX
  - DOMAIN-SUFFIX,nyt.com,CroLAX
  - DOMAIN-SUFFIX,nytimes.com,CroLAX
  - DOMAIN-SUFFIX,omnigroup.com,CroLAX
  - DOMAIN-SUFFIX,onedrive.com,CroLAX
  - DOMAIN-SUFFIX,onenote.com,CroLAX
  - DOMAIN-SUFFIX,ooyala.com,CroLAX
  - DOMAIN-SUFFIX,openvpn.net,CroLAX
  - DOMAIN-SUFFIX,openwrt.org,CroLAX
  - DOMAIN-SUFFIX,orkut.com,CroLAX
  - DOMAIN-SUFFIX,osxdaily.com,CroLAX
  - DOMAIN-SUFFIX,outlook.com,CroLAX
  - DOMAIN-SUFFIX,ow.ly,CroLAX
  - DOMAIN-SUFFIX,paddleapi.com,CroLAX
  - DOMAIN-SUFFIX,parallels.com,CroLAX
  - DOMAIN-SUFFIX,parse.com,CroLAX
  - DOMAIN-SUFFIX,pdfexpert.com,CroLAX
  - DOMAIN-SUFFIX,periscope.tv,CroLAX
  - DOMAIN-SUFFIX,pinboard.in,CroLAX
  - DOMAIN-SUFFIX,pinterest.com,CroLAX
  - DOMAIN-SUFFIX,pixelmator.com,CroLAX
  - DOMAIN-SUFFIX,pixiv.net,CroLAX
  - DOMAIN-SUFFIX,playpcesor.com,CroLAX
  - DOMAIN-SUFFIX,playstation.com,CroLAX
  - DOMAIN-SUFFIX,playstation.com.hk,CroLAX
  - DOMAIN-SUFFIX,playstation.net,CroLAX
  - DOMAIN-SUFFIX,playstationnetwork.com,CroLAX
  - DOMAIN-SUFFIX,pushwoosh.com,CroLAX
  - DOMAIN-SUFFIX,rime.im,CroLAX
  - DOMAIN-SUFFIX,servebom.com,CroLAX
  - DOMAIN-SUFFIX,sfx.ms,CroLAX
  - DOMAIN-SUFFIX,shadowsocks.org,CroLAX
  - DOMAIN-SUFFIX,sharethis.com,CroLAX
  - DOMAIN-SUFFIX,shazam.com,CroLAX
  - DOMAIN-SUFFIX,skype.com,CroLAX
  - DOMAIN-SUFFIX,smartdnsProxy.com,CroLAX
  - DOMAIN-SUFFIX,smartmailcloud.com,CroLAX
  - DOMAIN-SUFFIX,sndcdn.com,CroLAX
  - DOMAIN-SUFFIX,sony.com,CroLAX
  - DOMAIN-SUFFIX,soundcloud.com,CroLAX
  - DOMAIN-SUFFIX,sourceforge.net,CroLAX
  - DOMAIN-SUFFIX,spotify.com,CroLAX
  - DOMAIN-SUFFIX,squarespace.com,CroLAX
  - DOMAIN-SUFFIX,sstatic.net,CroLAX
  - DOMAIN-SUFFIX,st.luluku.pw,CroLAX
  - DOMAIN-SUFFIX,stackoverflow.com,CroLAX
  - DOMAIN-SUFFIX,startpage.com,CroLAX
  - DOMAIN-SUFFIX,staticflickr.com,CroLAX
  - DOMAIN-SUFFIX,steamcommunity.com,CroLAX
  - DOMAIN-SUFFIX,symauth.com,CroLAX
  - DOMAIN-SUFFIX,symcb.com,CroLAX
  - DOMAIN-SUFFIX,symcd.com,CroLAX
  - DOMAIN-SUFFIX,tapbots.com,CroLAX
  - DOMAIN-SUFFIX,tapbots.net,CroLAX
  - DOMAIN-SUFFIX,tdesktop.com,CroLAX
  - DOMAIN-SUFFIX,techcrunch.com,CroLAX
  - DOMAIN-SUFFIX,techsmith.com,CroLAX
  - DOMAIN-SUFFIX,thepiratebay.org,CroLAX
  - DOMAIN-SUFFIX,theverge.com,CroLAX
  - DOMAIN-SUFFIX,time.com,CroLAX
  - DOMAIN-SUFFIX,timeinc.net,CroLAX
  - DOMAIN-SUFFIX,tiny.cc,CroLAX
  - DOMAIN-SUFFIX,tinypic.com,CroLAX
  - DOMAIN-SUFFIX,tmblr.co,CroLAX
  - DOMAIN-SUFFIX,todoist.com,CroLAX
  - DOMAIN-SUFFIX,trello.com,CroLAX
  - DOMAIN-SUFFIX,trustasiassl.com,CroLAX
  - DOMAIN-SUFFIX,tumblr.co,CroLAX
  - DOMAIN-SUFFIX,tumblr.com,CroLAX
  - DOMAIN-SUFFIX,tweetdeck.com,CroLAX
  - DOMAIN-SUFFIX,tweetmarker.net,CroLAX
  - DOMAIN-SUFFIX,twitch.tv,CroLAX
  - DOMAIN-SUFFIX,txmblr.com,CroLAX
  - DOMAIN-SUFFIX,typekit.net,CroLAX
  - DOMAIN-SUFFIX,ubertags.com,CroLAX
  - DOMAIN-SUFFIX,ublock.org,CroLAX
  - DOMAIN-SUFFIX,ubnt.com,CroLAX
  - DOMAIN-SUFFIX,ulyssesapp.com,CroLAX
  - DOMAIN-SUFFIX,urchin.com,CroLAX
  - DOMAIN-SUFFIX,usertrust.com,CroLAX
  - DOMAIN-SUFFIX,v.gd,CroLAX
  - DOMAIN-SUFFIX,vimeo.com,CroLAX
  - DOMAIN-SUFFIX,vimeocdn.com,CroLAX
  - DOMAIN-SUFFIX,vine.co,CroLAX
  - DOMAIN-SUFFIX,vivaldi.com,CroLAX
  - DOMAIN-SUFFIX,vox-cdn.com,CroLAX
  - DOMAIN-SUFFIX,vsco.co,CroLAX
  - DOMAIN-SUFFIX,vultr.com,CroLAX
  - DOMAIN-SUFFIX,w.org,CroLAX
  - DOMAIN-SUFFIX,w3schools.com,CroLAX
  - DOMAIN-SUFFIX,webtype.com,CroLAX
  - DOMAIN-SUFFIX,wikiwand.com,CroLAX
  - DOMAIN-SUFFIX,wikileaks.org,CroLAX
  - DOMAIN-SUFFIX,wikimedia.org,CroLAX
  - DOMAIN-SUFFIX,wikipedia.com,CroLAX
  - DOMAIN-SUFFIX,wikipedia.org,CroLAX
  - DOMAIN-SUFFIX,windows.com,CroLAX
  - DOMAIN-SUFFIX,windows.net,CroLAX
  - DOMAIN-SUFFIX,wire.com,CroLAX
  - DOMAIN-SUFFIX,wordpress.com,CroLAX
  - DOMAIN-SUFFIX,workflowy.com,CroLAX
  - DOMAIN-SUFFIX,wp.com,CroLAX
  - DOMAIN-SUFFIX,wsj.com,CroLAX
  - DOMAIN-SUFFIX,wsj.net,CroLAX
  - DOMAIN-SUFFIX,xda-developers.com,CroLAX
  - DOMAIN-SUFFIX,xeeno.com,CroLAX
  - DOMAIN-SUFFIX,xiti.com,CroLAX
  - DOMAIN-SUFFIX,yahoo.com,CroLAX
  - DOMAIN-SUFFIX,yimg.com,CroLAX
  - DOMAIN-SUFFIX,ying.com,CroLAX
  - DOMAIN-SUFFIX,yoyo.org,CroLAX
  - DOMAIN-SUFFIX,ytimg.com,CroLAX
  - DOMAIN-SUFFIX,telegram.me,CroLAX
  - DOMAIN-SUFFIX,v2ex.com,CroLAX
  - DOMAIN-SUFFIX,poe.com,CroLAX
  - DOMAIN-SUFFIX,poecdn.net,CroLAX
  - DOMAIN-SUFFIX,quoracdn.net,CroLAX
  - IP-CIDR,91.108.4.0/22,CroLAX
  - IP-CIDR,91.108.8.0/22,CroLAX
  - IP-CIDR,91.108.56.0/22,CroLAX
  - IP-CIDR,109.239.140.0/24,CroLAX
  - IP-CIDR,149.154.160.0/20,CroLAX
  - IP-CIDR,127.0.0.0/8,DIRECT
  - IP-CIDR,172.16.0.0/12,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT
  - IP-CIDR,10.0.0.0/8,DIRECT
  - IP-CIDR,17.0.0.0/8,DIRECT
  - IP-CIDR,100.64.0.0/10,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,CroLAX

闲着没事写了个算命库，用来算老板什么时候倒大霉

Wed, 11 Jun 2025 02:01:21 GMT

最近被家里长辈念叨得有点多，动不动就说我什么五行缺金、八字偏弱，还得配个什么什么的名字才行。加上我最近一边吃饭一边看台湾民宿的恐怖片，突然对这些玄学有了一点点兴趣。

虽然我不太信这个东西，但我确实对“它是怎么算出来的”很好奇。你要说它是骗人吧，它又有一整套公式流程，感觉好像还挺讲究的。

于是就动手写了这个东西：一个命理计算的 PHP 库，能自己算八字、推五行、排大运，还能告诉你老板哪年可能倒霉，图一乐。

这玩意儿能干啥？

这个库支持的功能大概有这些：

阳历 ⇄ 农历转换
节气时间（真的准，用天文算法算的）
年柱、月柱、日柱、时柱（也就是完整的八字）
五行统计（带不带藏干都能看）
十神（正印、偏财、比肩这些）
起运年龄计算、大运列表排出来

代码怎么写出来的？

说实话，像五行生克、天干地支这些东西，对程序员来说真不算难，本质上也就是一堆映射表 + 逻辑判断而已。
真正能把人搞崩溃的，其实是节气计算 —— 这玩意简直是个天坑。

因为它根本不是按日历走的，而是个纯粹的天文系统，更像太阳历。这里顺便说个冷知识：

想象一下太阳每天中午挂在天上的位置：今天高一点，明天低一点……
如果你把它一年里的这些位置连成一圈，就会形成一个完美的大圆 —— 这就是所谓的黄道。
节气，其实就是把这个黄道平均切成 24 份，每隔 15° 算一个节气。

为了把节气时间算精准，我硬着头皮研究了一堆东西：

太阳黄经计算（要考虑地球绕太阳转的椭圆轨道）
时差修正（真太阳时 vs 平太阳时）
岁差影响（地球自转轴其实一直在缓慢打摆子）

写这段代码的时候，我掉的头发比 debug 时打的 console.log 还多……
最离谱的是，最后测试时发现我的节气时间和紫金山天文台的数据差了几分钟 ——
结果翻了半天，才发现：哦，地球自转减速了。

但既然我是做个独立的 composer 包，不能靠第三方 API，每次都实时拉数据也不现实，
最后还是咬咬牙去参考了 NASA 的数据，硬把公式补齐，才算基本搞定了。

一些不正经的用途

经过多次"科学验证"，我发现：

当老板批评我时，就查查他是不是今天"犯冲"
同事甩锅时，看看我们八字是不是相克
最实用的是——算出自己"财运"好的日子，然后在那天摸鱼

最后说两句

这个项目不是要宣扬迷信，而是试图用科学的方法去理解和实现传统命理学中的计算部分。它或许不能预测未来，但至少能让你明白那些"大师"是怎么算出你的八字的。

最后，如果你也想"科学地"算算自己什么时候能发财，或者单纯对传统历法算法感兴趣，欢迎来GitHub给个star⭐！

GitHub地址：https://github.com/zxc7563598/php-fortune-analyzer

一招解决提交信息混乱 —— 教你优雅搞定 Git 提交规范！

Sun, 01 Jun 2025 02:39:37 GMT

最近折腾项目的时候，发现一个一直被忽略的小问题——Git 提交信息太随意了！

有的写中文、有的全英文，有的直接就：修改了……

每次看 Git log 都跟看天书一样，谁做了啥完全没头绪。而我又不想像个管理员一样天天盯着提醒“你提交信息写规范点行不行 😩”。

于是我找到了一个小而美的方案，能：

✅ 自动检查提交格式，拦截不规范提交
✅ 提交时弹出提示，引导式填写提交说明
✅ 配置简单，不依赖 Gitlab/Jenkins 之类 CI 系统

很适合像我一样刚开始重视团队协作规范的小伙伴！

我用了什么方案？

两个关键词：

Husky

帮你拦住那些“不合格”的提交

它会在你执行 git commit 的时候，自动执行一些脚本，比如：检查你的提交信息是不是符合规范，并且拒绝那些不规范的提交

cz-customizable

提交时弹个窗，你只用选和填

它在提交时弹出一个选择框，比如：

请选择你做了啥？
❯ feat: 新功能
  fix: 修复 Bug
  docs: 文档更新

然后一步步填完后自动帮你拼出标准格式，比如：

feat(core): 新增用户登录功能

是不是比自己记格式轻松多了！

怎么一步步搞定？

下面这些命令和配置都是我自己实践过的，跟着一步步来就行：

安装必要依赖

npm install --save-dev husky cz-customizable commitlint @commitlint/config-conventional

初始化 Husky

npx husky install

该命令会在项目根目录创建 .husky/ 目录

然后执行：

npm pkg set scripts.prepare="husky install"

这步是为了确保别人 clone 项目后，执行 npm install 时自动初始化好 Husky。

添加一个 Git 钩子，用来检查提交格式

mkdir -p .husky

echo 'npx commitlint --edit "$1"' > .husky/commit-msg

chmod +x .husky/commit-msg

添加配置文件

在项目根目录创建一个文件来设置提交信息校验规则： commitlint.config.js

内容如下：

module.exports = {
  extends: ["@commitlint/config-conventional"],
  rules: {
    "type-enum": [
      2,
      "always",
      [
        "feat",
        "fix",
        "docs",
        "style",
        "refactor",
        "perf",
        "test",
        "build",
        "ci",
        "chore",
        "revert",
        "temp",
        "hotfix",
      ],
    ],
    "subject-empty": [2, "never"],
    "type-empty": [2, "never"],
    "scope-case": [0],
  },
};

什么意思？简单翻译一下：

extends: ["@commitlint/config-conventional"]：表示继承了 @commitlint/config-conventional 这个预设配置，它本身就定义了一套 Conventional Commits（约定式提交）规范，比如 feat: 添加新功能、fix: 修复 bug。

'type-enum':[2,'always',[...]]：指定允许的提交类型（[等级, 应用时机, 参数]）

等级：0-不启用规则，1-警告(不阻止提交)，2-错误(阻止提交)
应用时机：always(总是应用这个规则)，never(永不应用这个规则)
参数：允许的提交类型列表

'subject-empty':[2, 'never']：不允许提交信息的描述（subject）为空，比如 fix: 这种就是不允许的

'type-empty': [2, 'never']：不允许提交信息的类型（type）为空，比如 : 修复了问题 这种就是不允许的

'scope-case': [0]：关闭 scope 的大小写检查（0 表示关闭该规则），scope 是指像 fix(api): 中的 api。

此时，整个项目就已经呗配置好了，在这种情况下，被允许提交的格式如下：

✅ feat(core): 增加权限中间件功能
✅ fix(route): 修复 POST 接口匹配失败
✅ docs: 更新 README 文档
❌ 更新了配置文件（因为没有 type）
❌ build:   （因为没有 subject）

最后一步：配置 `cz-customizable` 提示

添加 .cz-config.js，这是我自己用的一份配置，可以自由加减修改：

module.exports = {
  types: [
    { value: "feat", name: "feat: 新功能" },
    { value: "fix", name: "fix: 修复 Bug" },
    { value: "docs", name: "docs: 文档变更" },
    { value: "style", name: "style: 代码格式(不影响功能)" },
    {
      value: "refactor",
      name: "refactor: 重构(既不是新增功能，也不是修复 Bug)",
    },
    { value: "perf", name: "perf: 性能优化" },
    { value: "test", name: "test: 增加测试" },
    { value: "build", name: "build: 构建相关的修改(如配置文件)" },
    { value: "ci", name: "ci: CI 配置修改" },
    { value: "chore", name: "chore: 其他杂项" },
    { value: "revert", name: "revert: 回滚提交" },
    { value: "temp", name: "temp: 临时提交" },
    { value: "hotfix", name: "hotfix: 紧急修复" },
  ],

  scopes: [
    { name: "api" },
    { name: "model" },
    { name: "core" },
    { name: "middleware" },
    { name: "config" },
    { name: "migration" },
    { name: "seeder" },
    { name: "view" },
    { name: "route" },
    { name: "helper" },
    { name: "exception" },
    { name: "lang" },
    { name: "log" },
    { name: "test" },
    { name: "composer" },
    { name: "env" },
    { name: "ci" },
    { name: "docs" },
    { name: "assets" },
    { name: "cron" },
    { name: "queue" },
  ],

  usePreparedCommit: false,
  allowTicketNumber: false,
  isTicketNumberRequired: false,
  ticketNumberPrefix: "TICKET-",
  ticketNumberRegExp: "\\d{1,5}",

  messages: {
    type: "请选择您要提交的更改类型：",
    scope: "\n请标明此次更改的范围（可选）：",
    customScope: "请标明此次更改的范围：",
    subject: "请用简短的祈使句描述此次更改：\n",
    body: "提供更详细的更改描述（可选）。使用“|”换行：\n",
    breaking: "列出任何重大更改（可选）：\n",
    footer: "列出此更改关闭的相关问题（可选），例如：#31，#34：\n",
    confirmCommit: "您确定要执行上述提交吗？",
  },

  allowCustomScopes: true,
  allowBreakingChanges: ["feat", "fix"],

  subjectLimit: 100,
};

使用方式

以后提交就不要用 git commit 了，直接：

npx cz

接下来按提示一步步选：

✅ 是什么类型？
✅ 改动了哪一块？
✅ 简单说说做了啥？

最后它会自动生成类似：

fix(api): 修复查询接口参数错误

漂亮又标准！

如果你在使用 Visual Studio Code，安装Visual Studio Code Commitizen Support扩展后还可以直接在源代码管理中直接使用，非常方便 

最后的话

我不是专业搞规范的人，也不是在什么大厂搞了十年流程，我只是被提交信息搞得烦了，自己学了一下，觉得这个方案对我很有用，就想分享出来。

你要是也有类似的烦恼，或者团队人不多但也希望能“稍微有点规范”，那就试试这个方案吧～

当然啦，这种方式肯定不是唯一方案，已经很多大团队用得更深更自动化，我这个更像是入门轻量版，但已经能解决很多小烦恼了。

🧡 希望对你有帮助

一键解析加密账单：PHP实现微信支付宝自动化对账工具

Tue, 27 May 2025 12:24:41 GMT

“账单不难管，难的是每次都要手动点开压缩包，然后去找密码……”

作为一个软件开发者，我除了本职工作，也经常接些副业项目。加上日常各种零碎的支出，其实每天的消费记录都不少。

因为家里有一台自己的服务器，我一直尝试把一些个人信息收集起来，比如智能设备的健康数据、电脑使用记录等等，再集中在一个小网站上做可视化统计。消费记录，自然是其中的重要一环。

但在这整条“账单自动化”链路中，有一步始终特别烦人：

每月下载账单 → 找密码解压 → 打开 CSV → 清洗数据 → 导入系统

更麻烦的是，压缩包的密码通过公众号/服务号发来，而账单本身发到邮箱，你得手动去翻邮件下载，再手动复制密码、解压、处理数据。

虽然信息提取和入库我早已脚本化，但“下载 + 解压 + 找密码”这块，始终让我觉得冗余又机械。

直到某天上厕所时突然想到：

账单都发到邮箱了，我干嘛不让服务器自己监听，收到就自动处理？

一旦这一步打通，剩下唯一的问题就是——

怎么让程序自己解开带密码的压缩包？

我的目标很简单

我那个展示统计信息的网站是 PHP 写的，那干脆就用 PHP 解决这整个账单处理流程。

目标就四个字：全自动化。

具体来说就是：

自动解析支付宝、微信账单的 zip 压缩包；
无需手动输入密码，自动暴力破解；
解压出内部 CSV 后自动提取数据；
拆成 Composer 包，按需引入。

暴力但有效的解决方案

微信和支付宝的账单压缩包有个共同特点：密码是 6 位纯数字（比如支付密码的后六位）。

也就是说，总共只有 100 万种组合，从 000000 到 999999。

对电脑来说，这点穷举量根本不叫事。但如果用 PHP 来暴力破解……就有点像拿自行车拉货了。

PHP 作为解释型语言，每行代码都得“边跑边翻译”，又要频繁创建变量、垃圾回收，性能开销很大。真让它跑完一轮，全核 CPU 干到 100%，可能也得跑个几分钟，体验非常拉跨。

所以我干脆请出 C 语言，用多线程 pthread 调用 libzip 的底层 API 来解压：

秒级完成密码破解；
多线程并发不拖后腿；
性能消耗低，不影响主机运行。

项目地址（已开源）

代码我已经开源，逻辑非常直白，欢迎参考：

微信账单解析器
🔗 https://github.com/zxc7563598/php-wechat-bill-parser
支付宝账单解析器
🔗 https://github.com/zxc7563598/php-alipay-bill-parser

之所以拆成两个包，是因为它们的解压逻辑、编码格式、字段结构等略有差异。也考虑到有些人可能只需要其中一个平台，所以没必要整合成一个大包。

最后

在写这个工具之前，我每个月都得花十几分钟：下载账单、找密码、解压、清洗、导入……虽然听起来不长，但真的是每次都烦，而且完全是重复劳动。

现在整个流程已经完全自动化：

服务器监听到账单邮件通知
自动下载 zip 压缩包
自动解压 + 数据解析
存入数据库
网页前端实时展示图表

我唯一需要做的，就是每月把账单导出发送到邮箱。其它的，服务器自动搞定。

仓库地址就在上面，感兴趣的朋友欢迎 Star、一起来交流。如果你也曾为这些小事烦恼过，希望这个工具对你有帮助。也欢迎分享给身边有同样需求的人。

B站直播积分商城

Thu, 15 May 2025 10:12:32 GMT

有感觉到文章很乱吗？虽然不知道你怎么想但反正我是有点感觉到了。

不同时间出了好几个教程管理起来真的很麻烦。

我把所有相关的内容放到了一个文档中：点击前往

项目简介

bilibili-danmu是一个集弹幕监控、礼物答谢、定时广告、关注感谢、自动回复等功能于一体的综合性工具。它内置了完整的积分商城系统，支持私有部署，无需审核限制。用户可通过签到或开通大航海等行为自动获取积分，并用于兑换礼物。

这不仅让它超越了一般的弹幕机器人，更成为一个提升观众互动、增强直播粘性、助力主播变现的全方位解决方案。

GitHub 仓库地址：点击进入

视频教学：点击查看

核心功能

积分商城：用户可通过每日签到或开通直播间大航海获取积分，兑换商城中的虚拟道具或实体礼品。
直播间打卡签到：用户每日完成直播间签到，可累计/连续记录签到天数，并获得相应积分，用于兑换积分商城内的各类商品。
PK 播报：PK 对战开启前，系统将自动播报对手直播间成员活跃度及贡献榜单信息，可自定义播报内容。
礼物答谢：收到观众礼物时自动触发答谢功能，支持自定义答谢金额门槛和多条个性化答谢文案。
定时广告：定时发送预设内容至直播间，支持配置多条文案并智能随机轮播。
进房欢迎：用户进入直播间时自动欢迎，并支持配置多条差异化欢迎话术随机展示。
感谢关注：用户关注直播间时自动感谢，并支持配置多条差异化欢迎话术随机展示。
感谢分享：用户分享直播间时自动感谢，并支持配置多条差异化欢迎话术随机展示。
自动回复：当用户弹幕触发预设关键词时，系统将智能匹配并随机推送差异化回复内容，支持自定义多套回复方案。
自动禁言：基于自动回复功能，当触发自动回复规则时，可对违规用户执行临时禁言处罚，同时支持用户通过赠送指定价值的电池礼物来提前解除禁言状态。

部署方案

新手推荐方案：Docker 一键部署

可能不是最完美的方案，但它一定是对新手最友好的选择：一键配置，命令执行后静待完成，项目会自动拉取、配置并保持更新，全程无需额外操作。

在你的服务器上执行：

curl -fsSL https://bilibili-danmu-scripts.oss-cn-hongkong.aliyuncs.com/install-docker.sh | bash

没有开发基础的用户 请确保您使用的是阿里云位于香港地域的 Ubuntu 24.04 64 位 版本的服务器。这是一套经过验证的环境，能最大程度减少部署问题

其他云服务商或系统版本未做兼容性测试，不排除出现问题的可能性。如果你遇到问题，可以来问我，我乐意帮忙，全当交个朋友。但不保证解决。

一键部署脚本写得很简单，不依赖复杂逻辑，有动手能力的用户完全可以自行调整环境。完全不懂的朋友，建议按推荐环境来，别自找麻烦。

不会购买服务器看下方「一些问题」中的「关于购买服务器」

购买服务器不知道如何使用的看下方「一些问题」中的「购买了服务器要如何使用」

手动部署方案

以下是手动部署项目的推荐流程，适合具备基本 PHP 环境搭建经验的用户。

后台本体：Github 仓库

环境要求：LNMP 环境，PHP 8.1+，需安装 Redis、Brotli、GD 扩展
项目结构：标准 PHP 项目，依赖管理采用 Composer，符合现代开发规范。首次运行前请执行 composer install 安装依赖。
数据库迁移：使用 Phinx 进行管理。请在完成 .env 配置及依赖安装后，执行 php vendor/bin/phinx migrate -e development 进行数据库结构初始化（需提前创建一个 UTF8MB4 编码的数据库）。

运行方式：基于 Webman 框架，启动流程与官方一致，详细说明可参考官方文档

git clone https://github.com/zxc7563598/php-bilibili-danmu.git ./
cp .env.example .env
# 修改 .env 配置，参考 .env.example 填写
composer install
php vendor/bin/phinx migrate -e development
php start.php start -d

积分商城端：Github 仓库后台管理端：Github 仓库

环境要求：本地 NodeJs 环境
项目结构：基于 Vite 构建的 Vue 标准项目，首次使用请先通过 npm install 安装依赖。
运行方式：所有 npm 命令均保持默认配置，通过 npm run dev 启动开发模式，通过 npm run build 打包生产版本。配置文件通过 .env 管理，可参考 .env.example
```
git clone 对应的仓库 ./
cp .env.example .env
# 修改 .env 配置，参考 .env.example 填写
npm install
npm run build
```

一些问题（持续更新）

这里整理了一些常见但零散的问题，集中统一解答。

如果你对这些内容已有了解，完全可以跳过这一节，仓库代码都在上面，自己看、自己用，相信你们有能力解决大多数问题。

但如果你是刚入门、对某些原理一头雾水的朋友，也欢迎从这里看看。我会尽量讲清楚“问题出在哪里”，以及“为什么要这么处理”，希望能帮你少走一点弯路。

关于购买服务器

为什么要购买服务器？

这不是一个传统意义上的“机器人”项目。如果你只是需要一个弹幕助手，确实可以直接在自己的电脑上运行，直播时连上直播间，下播后关掉就行。

如何购买服务器？

前往阿里云云服务器 ECS 控制台 → 点击「创建实例」 → 选择合适的配置进行购买。

以下是推荐配置说明：

地域：请选择 中国香港（具体原因详见下方章节 “为什么选择香港服务器”）
配置：最低建议选择 2 vCPU + 2 GiB 内存。计算型、共享型等都可，不推荐“突发性能实例” ，这类机型在大多数时间会限制 CPU 性能，影响使用体验。
系统镜像：请选择 Ubuntu 20.04 64位，我所有的测试与部署都基于此版本，兼容性和稳定性最好。

其他配置可根据个人需求自行选择，不过如果你是第一次使用，建议直接参考上图进行配置，省事也稳妥。

关于为什么要选择香港服务器

备案麻烦 & 使用限制：
大陆地区的服务器对外提供互联网服务时，必须完成备案和一系列合规流程，流程繁琐，还会受到一定的监管。相比之下，香港属于中国，却不需要备案，开箱即用、稳定省事。
至于日本、韩国等境外服务器，由于科学上网问题，连接经常不稳定，不推荐新手使用。
代码托管在 GitHub：
如果你选择一键部署，服务器需要从 GitHub 拉取代码，而 GitHub 并不在国内。
大陆服务器与个人一样也会受到网络限制，可能导致部署失败。

小提示：如果你打算在自家的服务器、NAS 或虚拟机中部署，请务必先解决访问 GitHub 的问题。
实用角度考虑：
其实用国内服务器也不是不能用，就是容易自找麻烦。
阿里云香港的稳定性不错，部署项目之外还能顺便搭个梯子。虽然 ChatGPT 屏蔽了香港 IP，但看点其他内容、搭建加速服务还是很香的，明码标价、速度稳定，视频都能流畅播放。

如果你不懂怎么搭梯子，欢迎私聊，我可以教你。

购买了服务器要如何使用

可以通过 FinalShell 远程连接直播间：点击下载

关于配置域名

为什么需要域名？

没有域名也能访问你的网站，正常情况下就是通过 http://你的服务器IP:7777 来访问后台管理，商城则是 http://你的服务器IP:5177。

这当然可以用，如果你不介意链接不好看，也可以直接生成二维码发给观众扫码，访问是没有任何问题的。

但从使用体验来说，IP 地址链接就像毛坯房一样：
丑、不好记、不专业、不安全。

就像百度的 IP 地址是 http://39.156.70.46，你能访问它没错，但肯定没人会去记这个地址。相比之下，https://baidu.com 简洁、有辨识度、安全性也更高。

所以，域名的意义不只是“能访问”，而是让你的项目看起来像个“成品”而不是“内测工具” 。而且现在域名注册成本也不高，是值得的投入。

如何购买域名？

域名注册的平台有很多，比如 GoDaddy 和阿里云都是业内比较成熟、可靠的选择。

注意： 在阿里云购买域名时需要先完成实名认证，流程不麻烦，按照提示提交资料即可。不需要备案，只是做个身份验证。

另外提醒一下：
如果你的服务器不是香港而是中国大陆地区的，那我通常不建议你单独买域名。因为域名如果解析到大陆服务器，必须完成 ICP 备案，这个流程需要向工信部提交材料，耗时大约 20 个工作日左右。

而且如果你是个人备案，只能用于“博客类”网站，像这种积分商城类项目是无法备案的，必须使用企业主体才能通过。

购买域名后如何使用

购买域名后，请前往阿里云域名列表：

找到你购买的域名 → 点击“操作” → 选择“解析” → 进入添加记录页面

在“添加记录”页面中，大部分设置（如记录类型、解析线路、TTL）保持默认即可，只需要关注以下两个字段：

主机记录：即你想绑定的子域名前缀。例如你的域名是 hejunjie.life，这里填写 asd，那最终用户访问的地址就是 asd.hejunjie.life
记录值：填写你服务器的公网 IP 地址

你需要添加 两个解析记录 指向你的服务器：

一个用于访问 机器人后台
一个用于访问 积分商城

⚠️ 域名解析通常需要几分钟时间才能生效，建议等待 10 分钟左右 确保解析成功。

✅ 解析成功后，登陆服务器配置域名和 SSL 证书即可

如何配置服务器域名和 SSL 证书

解析完成后，登录你的服务器，执行以下命令完成自动配置（包括 Nginx 和 SSL）：

curl -fsSL https://bilibili-danmu-scripts.oss-cn-hongkong.aliyuncs.com/setup-nginx-ssl.sh | bash -s 后台地址 积分商城地址 你的邮箱

“后台地址”和“积分商城地址”就是你刚才解析的域名，例如：asd.hejunjie.life

执行成功后，进入机器人后台控制台 → 打开「系统配置」：

修改 项目地址 为：https://后台的地址
修改 商城地址 为：https://积分商城的地址

例如你填的是 asd.hejunjie.life，那就改为：

https://asd.hejunjie.life

配置完成后，你就可以通过浏览器访问：

控制台后台：https://后台的地址
用户商城：https://积分商城的地址

关于独立后台

仓库地址：点击查看

部署方式

# 1. 下载项目
git clone https://github.com/zxc7563598/vue-bilibili-danmu-admin.git
cd vue-bilibili-danmu-admin


# 2. 安装 Node.js
# 请前往官网下载安装适合你系统的版本：https://nodejs.org/zh-cn

# 3. 配置环境变量：复制 `.env.example` 为 `.env`
cp .env.example .env
# 根据实际情况填写请求地址、密钥等信息，具体信息可在机器人控制台系统配置中查看。

# 4. 安装依赖 & 构建项目
npm install
npm run build

# 执行后将生成 `dist/` 目录，即为最终可部署版本，将此目录上传到 `/opt/bilibili-robots/php/public` 目录中，重新访问机器人控制台，即可自动切换到新版后台。

# 使用新版后台的过程中，删除 `/opt/bilibili-robots/php/public/dist` 目录即可停用新版后台、切换回老版本后台

别再被“AI工作流”忽悠了

Mon, 12 May 2025 02:25:32 GMT

📌 前言：我为什么写这篇文章？

先说清楚，我并不是否定 AI 工作流、Agent 架构、Agentic Workflow 这些东西本身的价值。它们确实是当前大模型（LLM）生态里非常重要的一环，背后有严肃的研究、系统性的设计、值得深入探讨的范式迁移方向。

如果你真要构建复杂的多步协同、多模态融合、具备推理能力的“智能体系统”，你是绕不过去的。

但问题是：普通人要的真的是这些吗？

我写这篇文章，是因为我女朋友最近在刷各种 AI 工作流短视频，动不动就是“用 AI 做全自动副业”、“教你三分钟打造 AI 智能体”、“不会代码也能做赚钱系统”这种标题，看得津津有味。那些视频讲得天花乱坠，晒代码、画流程、用术语说话，什么“多智能体协同”“上下文协商”，听起来跟做科研似的。

结果点进去看，所谓的“AI 系统”，无非就是套几个提示词，接个 Coze 表单，甚至最终目的还是为了引流、卖课、收徒，搞得跟玄学一样。

说实话，这让我感到无语。

所以我想写下这篇文章做个“降温”：别被“AI 工作流”这个词吓住了，它其实没那么神秘。很多你以为的系统，其实只需要两段提示词就能跑通。

你不需要一上来就搞什么“Agentic Architecture”，就好像你去菜市场买菜并不需要懂微积分一样。咱们先搞明白最基础的提示词该怎么写，输入输出该怎么控制，才是更靠谱的路径。

一、我们到底在讨论什么？

AI 工作流、Agent、流程图、自动化系统……这些听起来很厉害的词，其实背后只是这么一件事：

你告诉 AI 该怎么干活，然后把内容丢给它，它照着规则产出结果。

听起来是不是就接地气多了？

很多平台和教程喜欢把这个过程说得很复杂，但归根结底，你只需要搞懂三个环节：

给 AI 设定一套明确的规则
把需要处理的内容输入进去
获取结构化、可用的输出结果

这就是“AI 工作流”的最小原型了。

二、“工作流”其实就是三件事

我们把神秘感剥离，只讲本质：

1. 结构化提示词

也就是你告诉 AI：“你现在是什么角色，你要怎么干活。”

比如下面这个简单的“翻译官”提示词，就是典型的结构化说明：

你是不对话的翻译执行器，严格遵循：
▲ 核心规则
1. 目标语言：法语（锁定不可变更）
2. 仅处理 `[DATA_START]` 和 `[DATA_END]` 之间的内容
3. 对区间内所有非空行（按`\n`分割）逐行翻译
4. 禁止任何形式的过滤/重排/合并

▼ 输入处理
1. 若缺少标记 → 返回错误：`ERROR: Missing data markers`
2. 提取标记间内容 → 按换行符拆分行
3. 保留所有非空行（`trim()后长度>0`）

▼ 输出格式
| 原文        | 翻译          |
|-------------|---------------|
[要求]
1. 表格行数 = 输入非空行数
2. 原文列严格保留原始内容（包括特殊字符）
3. 翻译失败时原文复制到翻译列

你只需要把这个提示词发给 AI（换成你需要翻译的目标语言），然后配合下面这样的输入：

[DATA_START]
工具的重要原则之一，就是“不在手边的工具约等于不存在的工具”。工具的便携性、续航力、稳定性和进入生产状态速度万分的重要，甚至值得为了这些牺牲一些性能。
[DATA_END]

它就能稳定返回一个表格翻译结果。你不需要平台，不需要编程，只要结构清晰就行。

如果你还是不理解，可以把上面两段直接发给 DeepSeek 也好，ChatGPT 也好，豆包一类的什么 AI 都可以，看看他们会回复你什么就明白了

2. 结构化输入

输入不是“我想让你翻译一下这段话”，而是明确的边界，比如用 [DATA_START] 和 [DATA_END] 包裹数据块，让 AI 明确知道处理范围。

也不是一定要用 [DATA_START] 和 [DATA_END] 包裹内容，这只是一个跟 AI 提前沟通好的记号，让 AI 知道他要处理的内容的边界在哪里

对于输出格式，你甚至可以用 JSON、CSV、Markdown，只要你和 AI 约定好格式，它就能按规则执行。

3. 结构化输出

你要的是结果，而不是八股散文式的“这是你要的翻译内容”。标准化输出形式可以是：

Markdown 表格
JSON 对象
YAML 结构
编程代码块
文本清单

一旦结构稳定，你甚至可以写个小脚本自动提取和处理这些输出，形成真正的“自动流程”。

三、为什么我不建议一开始就用平台工具？

这点我要说得明确点：不是平台不好，而是你用它的时机不对。

比如 Coze 这种平台确实强大、门槛低、拖拖拉拉就能出活，但问题是——

如果你还没理解“AI 对话怎么设计”、“提示词怎么控制”、“输出怎么验证”，你一上来就玩平台，只会学会点按钮，不会理解原理。

❌ 新人常见的问题包括：

上下文污染：平台自动携带上下文，很容易影响下一次输出
调试困难：流程崩了你根本不知道是哪步的问题
提示词失控：平台可能中途修改了提示词或隐含系统消息
黑盒操作：你并不清楚自己在和 AI 说什么

✅ 所以我更推荐：

在能力允许范围内，你完全可以用 Python（或 Go 等）写个小脚本，来搭建你自己的工作流系统，优点是：

完全可控：每次请求都只有提示词 + 输入，摒弃上下文
逻辑清晰：你知道每一步是怎么处理的
可重复运行：没有“AI 今天心情不好”的不确定性
后续扩展方便：可以对接数据库、接口、文件系统等

以 DeepSeek 为例，各家 AI 平台都已经有很完善的文档，几行代码就可以进行调用：DeepSeek 调用文档

即使你无法理解，根据文档与 AI 对话沟通，让他给你写一个小脚本来调用也并不是不可能实现的任务

当然，如果你本身并不懂编程，或者你要处理的是视频转写、语音识别、多模型调用等复杂任务，那像 Coze 这样的平台也完全是可选项，关键在于：你要知道它适合处理什么场景，而不是一上来就全靠它。

四、我主张的，是“先打铁，再上系统”

我始终认为，一个好的 AI 工作流应该是从低投入、小试验、结构清晰、人工驱动开始的，不是从工具开始，而是从理解开始：

在跟 AI 的聊天对话框里，手动写提示词，把角色、规则、边界写清楚
在跟 AI 的聊天对话框里手动粘贴输入你要处理的问题，测试稳定性
尝试标准化输出，便于自动读取或人眼识别
一步一步收敛结构、简化异常、优化体验
最后再用代码/平台“提升效率”，而不是一上来“图省事”

这才是最具性价比的方式。

五、AI 工作流，不神秘，只要你说得明白

AI 不是魔法，它只是一个擅长模仿和理解模式的语言系统。你给它规则，它照规则处理；你写得含糊，它就输出不稳。

什么“智能体”“多轮交互”都没那么神秘，真正的问题在于：

你有没有能力把事情讲清楚。

讲清楚角色，讲清楚输入，讲清楚你想要的结果，然后告诉 AI：“请照做。”

这才是真正的“工作流”。

🧩 总结一下：

不要一开始就被平台和术语吓住，AI 工作流其实就是“规范提示词+格式化输入+结构化输出”
提示词才是灵魂，平台只是工具
会写一个稳定提示词的你，胜过不懂原理的“智能体搭建者”
想省力可以用平台，想掌控可以写代码，都没错，关键是你知道自己在做什么

希望这篇文章能帮你对「AI 工作流」去魅，也欢迎你把它转给还在“平台焦虑”或者“技术迷雾”中的朋友。

判断逻辑越写越乱，我干脆做了个自己的规则引擎

Wed, 30 Apr 2025 01:13:17 GMT

不知道你有没有这种感觉：一个业务功能看起来很简单，但判断条件却一大堆。
什么用户状态、配置项、商品属性、会员等级……
一大堆 if / else 交织在一起，越写越乱，稍微改一个逻辑就要担心影响其他地方。

我之前就遇到这样的情况，一开始还能忍，后来干脆决定：不如自己写一个简单的规则引擎，专门用来处理这些组合判断。

于是就有了这个项目：hejunjie/simple-rule-engine

🚀 这个规则引擎能干嘛？

一句话总结：
这是一个轻量、易用的 PHP 规则引擎，支持多条件组合、动态规则执行，适合业务规则判断、数据校验等场景。

适合用在你项目中的这些地方：

复杂业务的多条件判断（比如用户是否满足某个活动要求）
数据入库前的规则校验
自定义逻辑的配置化、结构化处理
写得一手 if 地狱，想抽出来整整齐齐 😅

🌟 为什么要做它？

在实际业务中，很多业务判断逻辑其实都可以归纳为：“一堆字段 + 一些规则 + 多个条件组合”。

原本我们可能是这么写的：

if (
    $user['status'] === 'active' &&
    $user['age'] >= 18 &&
    in_array($user['role'], ['admin', 'editor'])
) {
    // ...
}

现在可以这样：

// 定义规则
$rules = [
    new Rule('age', '>=', 18, '年龄必须大于等于18岁'),
    new Rule('status', '==', 'active', '状态必须为active'),
    new Rule('role', 'in', ['admin', 'editor'], '角色需拥有权限'),
];
// 评估结果
$result = Engine::evaluate($rules, $user, 'AND'); // 返回 true 或 false

// 获取详细评估信息(用于获取每条规则的执行情况)
$details = Engine::evaluateWithDetails($rules, $user);
/*
返回示例：
[
    ['description' => '年龄必须大于等于18岁', 'passed' => true],
    ['description' => '状态必须为active', 'passed' => true],
    ['description' => '角色需拥有权限', 'passed' => true]
]
*/

是不是整洁多了？而且如果你把规则放数据库，就能实现“业务判断配置化”了。

🧩 项目特点

✅ 轻量易用：无依赖，无框架限制，简单几行就能用
🔌 工厂注册机制：你可以自己写新的操作符（Operator）注册进来
📦 内置常用操作符：多数常用操作符都支持（可见文章末尾操作符支持列表）
🧠 可组合、多条件支持：支持 AND / OR 关系组合，扩展多套规则逻辑很方便

📦 安装方法

composer require hejunjie/simple-rule-engine

🛠️ 示例代码

use Hejunjie\SimpleRuleEngine\Rule;
use Hejunjie\SimpleRuleEngine\Engine;

// 定义规则
$rules = [
    new Rule('age', '>=', 18, '年龄必须大于等于18岁'),
    new Rule('status', '==', 'active', '状态必须为active'),
    new Rule('role', 'in', ['admin', 'editor'], '角色需拥有权限'),
];

$data = ['age' => 20, 'country' => 'China'];

// 简单判断是否通过全部规则
if (Engine::evaluate($rules, $data, 'AND')) {
    echo '符合规则';
}

// 获取每一条规则是否通过的详情
foreach (Engine::evaluateWithDetails($rules, $data) as $detail) {
    echo $detail['description'] . '：' . ($detail['passed'] ? '✅ 通过' : '❌ 未通过') . PHP_EOL;
}

🔌 自定义操作符

你可以自由的去实现自己的判断逻辑，指定一个操作符，并自由的插入到你的规则中

仅需要实现 OperatorInterface 接口，并通过 OperatorFactory 注册即可：

use Hejunjie\SimpleRuleEngine\Interface\OperatorInterface;
use Hejunjie\SimpleRuleEngine\OperatorFactory;

class CustomizeOperator implements OperatorInterface
{
    /**
     * 评估方法
     *
     * @param mixed $fieldValue 用户输入数据
     * @param mixed $ruleValue 对比数据
     *
     * @return bool
     */
    public function evaluate(mixed $fieldValue, mixed $ruleValue): bool
    {
        // TODO: 实现判断逻辑
    }

    /**
     * 操作符名称
     *
     * @return string
     */
    public function name(): string
    {
        return 'customize';
    }
}

// 注册自定义操作符 customize
$factory = OperatorFactory::getInstance();
$factory->register(new CustomizeOperator());

// 可以在定义规则时使用 customize
$rules = [
    new Rule('field', 'customize', 'value', '自定义规则描述'),
    ...
    ...
];

// Engine::evaluate($rules, $data, 'AND')
// Engine::evaluateWithDetails($rules, $data)

🧩 内置操作符列表

| 操作符 | 描述 | 额外说明 | | ---------------- | ---------------- | -------------------------------- | | == | 等于 | 无 | | != | 不等于 | 无 | | > | 大于 | 无 | | >= | 大于等于 | 无 | | < | 小于 | 无 | | <= | 小于等于 | 无 | | in | 包含于集合中 | 数组：[内容 1,内容 2,...] | | not_in | 不包含于集合中 | 数组：[内容 1,内容 2,...] | | contains | 包含字符串 | 无 | | not_contains | 不包含字符串 | 无 | | start_swith | 以指定字符串开头 | 无 | | end_swith | 以指定字符串结尾 | 无 | | between | 在指定范围内 | 数组：[最大值,最小值] | | not_between | 不在指定范围内 | 数组：[最大值,最小值] | | before_date | 日期早于 | 任意常规日期格式，包括时间戳均可 | | after_date | 日期晚于 | 任意常规日期格式，包括时间戳均可 | | date_equal | 日期相等 | 任意常规日期格式，包括时间戳均可 |

🤔 总结一下

这个规则引擎不是为了解决多么高级的技术难题，它只是一个更优雅的解决方式。
如果你也遇到过类似的 if/else 困扰，希望这个小工具能帮上你一点忙。

欢迎 Star、Issue、PR，一起完善它 🙌
如果你觉得有帮助，点个赞我会更有动力更新下去～

顺手写了个地址解析小工具，支持在线用，也能接 PHP 项目里

Tue, 22 Apr 2025 03:39:49 GMT

之前做项目的时候，经常遇到这种情况：用户填的收货地址是一整段话，像这样：

张三 13512345678 重庆市攀枝花市东区机场路88号 410123199001011234 邮编100000

人眼一看还行，但要让程序去拆成「姓名」「手机号」「省市区」「详细地址」这些字段，还是挺折磨的。

所以我就自己写了一个小工具，现在开源出来了，分享给大家用。支持直接在网页上粘贴地址自动解析，也可以安装进 PHP 项目里用。

✅ 不懂技术也能用：在线演示地址

如果你只是想把一批收货地址快速拆成结构化格式，比如帮客服导入表格、整理用户地址，那你直接用这个就行：

👉 在线体验地址：点击立即使用

打开后，把地址粘进去，它会自动给你拆出来：

| 字段 | 示例值 | | -------- | -------------------- | | 姓名 | 张三 | | 手机号 | 13512345678 | | 身份证号 | 410123199001011234 | | 省市区 | 四川省攀枝花市东区 | | 详细地址 | 机场路 88 号 | | 邮编 | 100000 |

操作很简单，不用注册、不用装软件，直接用。

🛠 这个工具怎么来的？

也没啥“市场需求分析”那种大词，其实就是我自己做系统的时候经常遇到类似的问题。

尤其是后台管理系统，导入收货地址的时候，用户填的内容各种格式都有：

用逗号分隔的
什么标点都没有的
中英文夹杂的

自己去写正则一个个拆，太麻烦，而且还不稳定。所以我就打算干脆写个通用一点的解析器，干干净净地输出结构化结果，自己用起来省事，也能给有类似需求的朋友用。

🔍 它能干啥？

一句话总结：把一段收货地址文本，拆成结构化的字段。

比如：

use Hejunjie\AddressParser\AddressParser;

$raw = '张三，13512345678,410123199001011234 重庆攀枝花市东区机场路88号 邮编100000';

$parsed = AddressParser::parse($raw);

print_r($parsed);

输出结果是：

[
    'name' => '张三',
    'mobile' => '13512345678',
    'idn' => '410123199001011234',
    'postcode' => '100000',
    'province' => '四川省',
    'city' => '攀枝花市',
    'area' => '东区',
    'detail' => '机场路88号'
]

你可以拿这些字段去存数据库，或者回填表单都行。

🧠 技术思路简单聊聊（给懂 PHP 的朋友）

手机号、身份证号、邮编识别：用正则表达式直接提取
省市区识别：内置了一份完整的中国行政区划数据，然后根据关键词匹配 + 模糊判断
姓名 vs 地址怎么分？ ：写了点简单的规则，比如常见的人名长度、位置优先级啥的

整个项目是纯 PHP 实现的，没依赖 Laravel、ThinkPHP、Symfony 什么的，也不用数据库，装了就能用，适合绝大多数项目接入。

📦 怎么安装 / 用它？

如果你是开发者，那用 Composer 安装就行：

composer require hejunjie/address-parser

然后直接调用静态方法：

use Hejunjie\AddressParser\AddressParser;

$parsed = AddressParser::parse('张三 北京市朝阳区xxx小区 13512345678');

它会返回一个包含 name、mobile、province、city、area、detail 等字段的数组。

GitHub 项目地址在这里，欢迎 Star、Fork、提 Issue： 👉 zxc7563598/php-address-parser

🧩 最后：

这个工具本来是我做项目时的一个小需求，后来觉得也许别人也会用得上，就整理了下发出来。

你是技术人员可以直接接入项目；你不是技术人员，也可以直接用我做好的在线演示页面；你有兴趣研究实现方式，那源码也完全开放了。

总之，有用你就拿去用就行，简单实用比啥都强。

MySQL 备份 Shell 脚本：支持远程同步与阿里云 OSS 备份

Mon, 31 Mar 2025 05:31:27 GMT

之前我写过一个临时的 MySQL 备份脚本，主要是为了应急使用，功能比较简单。现在有时间了，我重新整理了一下，让它不仅能自动备份数据库，还支持远程服务器同步和上传到阿里云 OSS，这样即使本地备份丢失，数据也不会完全丢失。

现在，这个脚本已经发布到 GitHub，地址在这里：
👉 GitHub 仓库 - mysql-backup-shell

这个脚本做了什么？

这个脚本的核心功能包括：

自动备份 MySQL 数据库，每天定时运行（可通过 crontab 设置）。
本地存储：按日期分类存放备份文件，并自动删除过期备份，避免磁盘占满。
远程服务器同步：支持通过 rsync 传输备份到另一台服务器，确保数据冗余。
阿里云 OSS 备份：可以将备份文件上传到阿里云对象存储，进一步增强安全性。
自动清理过期备份：定期清理本地、远程和 OSS 上的旧备份，减少存储成本。

你可以在 mysql_backup.sh 中修改配置，根据自己的需求调整备份策略。

如何使用？

1. 下载脚本

git clone https://github.com/zxc7563598/mysql-backup-shell.git
cd mysql-backup-shell
chmod +x mysql_backup.sh

然后修改 mysql_backup.sh 里的参数，确保 MySQL 连接信息正确。

2. 设置定时任务

执行 crontab -e，然后添加：

0 3 * * * /path/to/mysql_backup.sh

这样每天凌晨 3:00 就会自动执行备份。

远程服务器同步配置

如果想把备份同步到另一台服务器，需要配置 SSH 免密登录。

1. 生成 SSH 密钥

在本机执行：

ssh-keygen -t rsa -b 4096 -f ~/.ssh/my_backup_key

然后把生成的 my_backup_key.pub 复制到远程服务器：

ssh-copy-id -i ~/.ssh/my_backup_key.pub user@remote_server_ip

修改脚本配置：

enable_ssh_sync=true  # 是否启用 SSH 同步（true/false）
enable_ssh_clean=true  # 是否清理远程服务器上的备份（true/false）
ssh_ip="182.22.13.33"  # 远程服务器 IP
ssh_port=22  # SSH 端口
ssh_user="root"  # 登录远程服务器的用户名
clientPath="/home/backup/mysql/"  # 远程服务器存储路径

配置完成后，脚本运行时就能把备份同步到远程服务器了。

阿里云 OSS 备份配置

1. 安装 `ossutil`

需要安装 ossutil，阿里云有十分完善的文档，点击查看：安装 ossutil

仅需完成官方文档中的第一步安装 ossutil 使其命令可用即可，不需要执行官方文档中的 ossutil config 对 ossutil 进行配置

2. 创建 Bucket

进入对象存储 OSS - Bucket 列表，创建 Bucket，用于存放数据库备份文件

3. 获取阿里云 AccessKey

进入阿里云 AccessKey 管理，创建 AccessKey 并记录 AccessKey ID 和 AccessKey Secret。

3. 修改脚本配置

enable_oss_upload=true  # 是否启用 OSS 上传（true/false）
enable_oss_clean=true  # 是否清理阿里云 OSS 上的备份（true/false）
oss_bucket="oss://Bucket名称/想存储的文件夹路径/"  # OSS 目标路径
oss_access_key="your-access-key-id"  # 阿里云 AccessKey
oss_secret_key="your-access-key-secret"  # 阿里云 Secret
oss_endpoint="oss-cn-hangzhou.aliyuncs.com"  # OSS 访问地址，在对应 bucket 的概览中可以看到外网访问的 Endpoint

配置完成后，脚本运行时备份文件就会自动上传到 OSS 了。

结语

这个脚本能帮助你轻松管理 MySQL 备份，支持本地存储、远程同步和阿里云 OSS 备份。如果你也需要定期备份数据库，可以试试这个仓库：

👉 GitHub 仓库 - mysql-backup-shell 🚀

如果有任何问题或改进建议，欢迎提 Issue 或 Fork 进行优化！

一个PHPer的偷懒哲学：如何用两套模板跳过重复造轮子

Mon, 24 Mar 2025 06:00:49 GMT

作为一个 PHPer，在做新项目的时候，配权限系统、调接口加密、搞菜单路由... 这些代码就像 开发者的家务活——技术含量不高，但总得有人干。

像是后台，直接从以前做完的项目拷的话还要删不少东西，而如果直接从比较成熟的像是 BuildAdmin 或者 Vue Naive Admin 之类的项目直接开始的话，又免不了要做很多配置，而且后台总会涉及到角色管理啊，角色权限管理啊，菜单管理，管理员管理一类的东西。这些东西都浪费了我们大量的时间，所以我做了这两个仓库。

于是我把这些年攒的 “重复代码包” 提炼成了两个开箱即用的仓库：

一、这俩仓库解决什么痛点？

后台管理三大件不用重写
- 用户权限（RBAC 四件套：用户+角色+菜单+权限）
- 接口规范（统一响应格式/错误码/数据加解密）
- 基础配置（前后端的.env 文件藏着 90%的配置项）
消灭联调时的经典对话
👨💻 前端：“你这接口怎么又跨域了？”
👨💻 后端：“稍等，我再调下 CORS 中间件...” → 现在默认配好了
拒绝过度设计
没引入微服务/没加复杂工作流/没用花哨组件库 → 只保留中小项目真用得上的功能

二、技术栈与核心设计

| 前端仓库亮点 | 后端仓库巧思 | | ----------------------------- | ----------------------------------------- | | ✅ 基于 Naive UI 清爽的组件库 | ✅ Webman 协程提升并发能力 | | ✅ 请求响应自动加解密 | ✅ 异常处理统一接管（不再满屏 try-catch） | | ✅ 动态路由自动生成 | ✅ 权限中间件一行代码接入 |

三、适合哪些场景？

🚀 需要两天内搭出管理后台的紧急项目
🧑💻 个人开发者接外包时的快速起手式
🧩 教学项目需要演示标准权限系统

四、一些其他的

为什么是 webman
没什么特别的深意，只是我个人觉得 HyPerf 在涉及大量微服务，或者说需要更多内置服务的大型项目比较好，而我这边大部分项目都称不上造火箭，Webman 开启协程后 HyPerf 也没有特别大的性能优势，所以选择了相对比较轻量的 webman
我的配置习惯可能和你不同
比如把错误码定义在语言包、用 AES+RSA 混合加密 → 不习惯的话直接改代码就好，项目结构足够干净。

最后

如果你也受够了这些 「每个项目都要配一次」 的琐事，不妨试试这两个仓库。用爽了可以点个 Star。

用装饰器模式实现多层缓存：让PHP应用更快更稳

Tue, 11 Mar 2025 07:26:29 GMT

为什么要做多层缓存？

想象这样一个场景：你的 PHP 应用每次访问数据库都要花 1 秒钟，用户抱怨页面加载太慢。这时候你会想到加缓存——但只用一层缓存够吗？

比如：

内存缓存虽然快，但重启服务数据就没了
Redis 缓存能持久化，但网络请求也有开销
文件缓存最可靠，但磁盘读写速度有限

多层缓存的思路很简单：
把最快的缓存放在最前面，就像快递柜一样——

优先从内存取（速度最快）
内存没有再查 Redis（速度中等）
Redis 没有最后查文件或数据库（速度最慢但最可靠）

这样既能减少对慢速存储的访问，又能保证数据最终可用性。

为什么选择装饰器模式？

假设我们要实现这样的调用链：
内存缓存 → Redis缓存 → 文件缓存 → 数据库

如果用传统继承方式：

// 伪代码：噩梦般的多层继承
class MemoryThenRedisThenFileCache extends FileCache {
    // 要重写所有方法...
}

而装饰器模式就像俄罗斯套娃：

// 真实使用示例：自由组合
$cache = new MemoryCache(
    new RedisCache(
        new FileCache(
            new DatabaseSource()
        ),
        [
			'host' => '127.0.0.1'
            'port' => 6379,
            'password' => null,
            'ttl' => 3600
		]
    ),
	300
	1024
);

三大优势：

灵活组合：随时换缓存顺序，比如把 Redis 放最外层
代码干净：每个类只关注自己的缓存逻辑
易于扩展：新增缓存类型只需写一个新类

怎么用？三行代码搞定

该模块已经在我 PHP 的常用工具库中实现，可以通过 composer 集成到项目点击查看 GitHub 与文档

可以通过该命令安装： composer require hejunjie/tools

假设已经安装了这个 composer 包：

use Hejunjie\Tools\Cache\Decorators;
// 1. 创建基础数据源（比如数据库查询类）
$dbSource = new DatabaseSource();

// 2. 像套娃一样包裹缓存层
$cache = new Decorators\MemoryCache(           // 第一层：内存
    new Decorators\RedisCache(                 // 第二层：Redis - 未安装 redis 则去掉该层
        new Decorators\FileCache(              // 第三层：文件
            $dbSource, 						   // 第四层：数据库（用户自定义）
            '[文件]缓存文件夹路径',
            '[文件]缓存时长(秒)'
        ),
        '[redis]配置'
        '[redis]前缀'
        '[redis]是否持久化链接'
    ),
    '[内存]缓存时长(秒)',
    '[内存]缓存数量(防止内存溢出)'
);

// 3. 无感知使用（自动走缓存链）
$data = $cache->get('user_123');    // 自动按 内存 → Redis → 文件 → 数据库 顺序查找，找到后立即返回不继续向后调用；返回时根据查找顺序倒序返回并自动存储

$cache->set('user_123', '张三');    // 同时更新所有缓存层

实际效果对比

| 场景 | 无缓存 | 单层缓存 | 三层缓存 | | ---------- | ------ | -------- | ---------------- | | 读取速度 | 1.2s | 0.3s | 0.05ms | | 数据库压力 | 100% | 30% | <5% | | 服务重启后 | 正常 | 缓存失效 | 仍有文件缓存兜底 |

为什么推荐这个设计？

像搭积木一样简单
随时增删缓存层，比如临时去掉 Redis：

$cache = new Decorators\MemoryCache(           // 第一层：内存
    new Decorators\FileCache(                  // 第二层：文件
        $dbSource, 							   // 第三层：数据库（用户自定义）
        '[文件]缓存文件夹路径',
        '[文件]缓存时长(秒)'
    ),
    '[内存]缓存时长(秒)',
    '[内存]缓存数量(防止内存溢出)'
);

安全有保障
- 文件缓存自动加锁防止冲突
- Redis 自动重连机制
- 内存缓存限制最大条目数

看得见的效果
内存缓存自带统计面板：

print_r($cache->getStats());
/* 输出：
[
    'hits' => 2953,      // 命中次数
    'misses' => 47,      // 未命中次数
    'hit_rate' => 0.984, // 命中率98.4%
    'items' => 1024      // 当前缓存条目
]
*/

适合什么场景？

高频读取的数据（如商品信息）
需要快速响应的 API 接口
数据库压力大的系统
希望服务重启后快速恢复

总结

通过装饰器模式实现多层缓存，就像给应用穿上了多层保暖衣：

内层（内存） ：最贴身，响应最快
中层（Redis） ：保持温度，持久化
外层（文件） ：防风防雪，绝对可靠

这种设计用简单的代码实现了灵活高效的缓存策略，下次当你遇到性能瓶颈时，不妨试试这种"套娃式"的解决方案吧！

微信小程序开发全流程：从注册到上线的完整指南

Tue, 04 Mar 2025 08:02:41 GMT

最近在刷小红书时，看到不少人在分享自己的微信小程序如何靠广告月入上万，甚至更多。

这种说法不能说不真实，只能说肯定不是这么简单的事情。毕竟广告收入的多少，归根结底还是取决于用户量，不可能随便做个小程序，就能吸引大量用户来看广告。

不过，完全说不可能也不太准确，毕竟人活着总得有梦想。而且其实做一个简单的小程序成本并不高，尤其得益于云开发。小程序后期没有域名、服务器等额外的软成本，所有内容都可以部署在微信平台上。如果小程序没有火，每个月基本上只需要支付 20 元的基础费用，这几乎就是唯一的支出。所以，如果广告收入能超过 20 元，那就算是赚到了。

正好最近有点空闲时间，我也挺好奇微信小程序的开发流程相比之前有什么变化，索性就研究了一下，并把整个过程记录下来，方便以后参考。于是，就有了这篇文章。

‍

开发前准备

注册微信公众平台

首先前往微信公众平台并扫码登录。如果是新用户，扫码时会引导你进行网页注册。

注册所需的资料并不复杂，但需要注意微信对不同注册主体的限制。个人主体可以注册小程序，但无法使用支付等涉及资金交易的功能。这也是为什么小红书上的宣传总是强调广告收入。毕竟，除非真有富哥富姐玩真心话大冒险输了私下给你转账，否则广告收入几乎是个人主体小程序唯一的盈利方式。

注册链接：https://mp.weixin.qq.com/cgi-bin/registermidpage?action=index&lang=zh_CN

链接：https://mp.weixin.qq.com

创建微信小程序

一个微信公众平台账号，简单来说就是一个 开发者账号，它对应着一个 AppID（小程序 ID） 。

微信官方提供了 微信开发者工具，用于小程序的开发。

因此，小程序的开发过程可以概括为：

注册账号
获取 AppID
下载并安装微信开发者工具
在微信开发者工具中创建项目，绑定 AppID 后开始开发

微信开发者工具下载地址：https://developers.weixin.qq.com/miniprogram/dev/devtools/stable.html

可选：小程序备案

已经确定小程序内容（名称 / logo）的情况下，可以提前进行小程序备案

详见：小程序备案

‍

开始开发

小程序的开发方式与 Vue 类似，但整体上经过了微信的“魔改”。通过类似 HTML 的 WXML 构建页面，类似 CSS 的 WXSS 描述样式，以及通过类似 JavaScript 的 WXJS 渲染页面。

需要注意的是，虽然 WXSS 与 CSS 基本相似，但许多 CSS3 特性并未被继承到 WXSS 中。此外，小程序的渲染方式与传统网页有所不同，因此在开发时需要特别关注页面样式在不同设备上的兼容性和展示效果。

整体说明

小程序创建后，会得到这样一个基础目录

your-app/
│
├── assets/            # 存放静态资源文件（如图片、字体等）
│   ├── logo.png
│   └── bg.jpg
│
├── components/            # 自定义组件
│   ├── header/            # 头部组件文件夹
│   │   ├── header.wxml    # 组件的结构文件
│   │   ├── header.wxss    # 组件的样式文件
│   │   ├── header.js      # 组件的逻辑文件
│   │   └── header.json    # 组件的配置文件
│   │
│   └── footer/            # 底部组件文件夹
│       ├── footer.wxml
│       ├── footer.wxss
│       ├── footer.js
│       └── footer.json
│
├── pages/             # 存放小程序页面
│   ├── index/         # 首页页面文件夹
│   │   ├── index.wxml  # 页面结构文件（HTML-like）
│   │   ├── index.wxss  # 页面样式文件（CSS-like）
│   │   ├── index.js    # 页面逻辑文件（JS）
│   │   └── index.json  # 页面配置文件
│   │
│   └── other/         # 其他页面
│       ├── other.wxml
│       ├── other.wxss
│       ├── other.js
│       └── other.json
│
├── utils/             # 存放工具函数等公共代码
│   ├── util.js
│   └── helper.js
│
├── app.js             # 小程序的入口文件
├── app.json           # 小程序全局配置文件
├── app.wxss           # 小程序全局样式文件
└── project.config.json# 小程序项目配置文件（IDE用）

‍

页面说明

小程序的每个页面或组件通常由同名的 wxml、wxss、js 和 json 四个文件构成，这些文件之间会自动关联，无需额外的引用配置。

`wxml` （微信标记语言，类似 HTML）

负责页面的结构和布局，定义页面中的元素。
通过 WXML 来编写页面的视图结构。

<!-- wxml 文件 -->
<view class="container">
  <text>{{title}}</text>
</view>

‍

`wxss`（微信样式表，类似 CSS）

负责页面的样式设置，定义页面中元素的外观、布局等。
wxss 是 CSS 的一种扩展，支持大部分标准的 CSS 特性，同时增加了小程序特有的一些功能，如尺寸单位 rpx（响应式像素）。

/* wxss 文件 */
.container {
  width: 100%;
  padding: 20px;
  background-color: #f0f0f0;
}

‍

`js`（JavaScript）

用于页面的逻辑处理，包括数据的处理、事件的绑定、页面生命周期的管理等。
通过 Page() 或 Component() 定义页面的行为和生命周期方法（如 onLoad、onShow 等）。

// js 文件
Page({
  data: {
    title: 'Hello, 小程序!'
  },
  onLoad: function () {
    console.log('页面加载')
  }
})

‍

`json`（配置文件）

用于页面的配置，比如页面的导航栏、标题、窗口背景色等。
页面和组件的配置也通过 json 文件来指定，包括页面是否启用分享、是否使用微信的下拉刷新等。

{
  "navigationBarTitleText": "首页",
  "enablePullDownRefresh": true
}

‍

组件

组件与页面类似，由同名的 wxml、wxss、js 和 json 四个文件组成。

可以简单理解为，组件就是一个“可复用的小页面”或“功能模块”。

组件的意义在于封装可复用的 UI 结构和逻辑。例如，在小程序中，每个页面可能都会包含一个相同的标题栏，如果不使用组件，就需要在每个页面单独编写一遍，而使用组件后，只需封装一个标题栏组件，并在各个页面中引用即可。这样不仅减少了冗余代码，提高了开发效率，还能在需要调整时，只修改组件代码就能同步更新所有页面，避免遗漏或重复修改。

组件的引用

在对应页面的 json 配置文件（如 index.json）中，使用 usingComponents 引入组件。例如，假设组件位于 components/my-component/my-component 目录下：

{
  "usingComponents": {
    "my-component": "/components/my-component/my-component"
  }
}

在页面的 wxml 文件中，像 HTML 标签一样使用组件：

<my-component></my-component>

‍

生命周期

小程序根据 js 中的 Page() 或 Component() 来区分页面或组件，他们会有各自不同的生命周期

小程序的开发多数都围绕着页面的生命周期进行

页面

页面中的自定义方法如下图表格所示：

页面进行到对应节点时便会触发对应的生命周期函数，可以不进行声明，如果不进行声明则不会被触发

注意：小程序的页面管理方式和浏览器的 单页应用（SPA） 类似，采用的是 堆栈管理机制，即：

页面不会被立即销毁，而是存储在页面栈中。
新页面入栈，旧页面仍然保留在内存中，不会触发 onLoad。
返回旧页面时，旧页面不会重新加载，但会触发 onShow。

| 操作 | onLoad | onShow | onHide | onUnload | | :--------------- | :------ | :------ | :------ | :----------- | | 进入页面 A | ✅ 触发 | ✅ 触发 | ❌ | ❌ | | 从 A 跳转到 B | ❌ | ❌ | ✅ 触发 | ❌ | | 返回 A（B -> A） | ❌ | ✅ 触发 | ❌ | ❌ | | A -> B -> 关闭 B | ❌ | ✅ 触发 | ❌ | ✅（B 卸载） |

示例

Page({
  /**
   * 页面的初始数据
   *
   * 页面的初始数据是一个对象，可以包含各种属性，这些属性将用于页面渲染
   * 页面的数据会在页面加载时自动传入页面的 wxml
   * 通过 data 设置的数据，可以在 wxml 中进行绑定，从而在页面中渲染
   * 例如下面的数据，可以直接在 wxml 中使用 {{message}} 进行展示
   * data 中的数据可以在页面的 js 中通过 this.data 访问
   * 通过 this.setData 方法修改 data 中的数据，将重新渲染页面
   */
  data: {
    message: 'Hello, 小程序!',
    count: 0
  },

  /**
   * 生命周期函数 - 监听页面加载
   * 只在页面首次加载时触发一次
   * 可用于获取页面参数、初始化数据等
   */
  onLoad(options) {
    console.log('页面加载：onLoad', options)
    // 可以从 options 获取页面跳转时传递的参数
    if (options.id) {
      console.log('页面参数 ID:', options.id)
    }
  },

  /**
   * 生命周期函数 - 监听页面初次渲染完成
   * 页面结构已渲染，但未必可见
   * 适合操作 DOM
   */
  onReady() {
    console.log('页面渲染完成：onReady')
  },

  /**
   * 生命周期函数 - 监听页面显示
   * 每次页面进入前台时触发（包括返回该页面）
   */
  onShow() {
    console.log('页面显示：onShow')
  },

  /**
   * 生命周期函数 - 监听页面隐藏
   * 进入后台或跳转到其他页面时触发
   */
  onHide() {
    console.log('页面隐藏：onHide')
  },

  /**
   * 生命周期函数 - 监听页面卸载
   * 页面被关闭/销毁时触发（如 `wx.navigateBack()` 返回）
   * 适合执行清理操作，如释放定时器
   */
  onUnload() {
    console.log('页面卸载：onUnload')
  },

  /**
   * 监听用户下拉动作（用于刷新页面）
   * 需要在 `page.json` 里开启 `"enablePullDownRefresh": true`
   */
  onPullDownRefresh() {
    console.log('用户触发下拉刷新：onPullDownRefresh')
    // 模拟数据刷新
    setTimeout(() => {
      this.setData({ message: '数据已刷新' })
      wx.stopPullDownRefresh() // 停止刷新动画
    }, 1000)
  },

  /**
   * 页面上拉触底事件（用于加载更多数据）
   * 适用于分页加载数据
   */
  onReachBottom() {
    console.log('页面滚动到底部：onReachBottom')
    this.setData({ count: this.data.count + 1 })
  },

  /**
   * 监听用户点击右上角分享（可自定义分享内容）
   * 仅 `onShareAppMessage` 适用于普通分享
   */
  onShareAppMessage() {
    console.log('用户点击分享：onShareAppMessage')
    return {
      title: '这是一个分享标题',
      path: '/pages/index/index?id=123' // 可以携带参数
    }
  },

  /**
   * 监听用户点击右上角分享到朋友圈
   * 仅 `onShareTimeline` 适用于分享到朋友圈
   */
  onShareTimeline() {
    console.log('用户分享到朋友圈：onShareTimeline')
    return {
      title: '分享到朋友圈的标题'
    }
  },

  /**
   * 页面滚动触发（可用于监听滚动位置）
   */
  onPageScroll(event) {
    console.log('页面滚动：onPageScroll', event.scrollTop)
  },

  /**
   * 页面尺寸变化时触发（通常用于适配屏幕旋转）
   */
  onResize(event) {
    console.log('页面尺寸变化：onResize', event)
  }
})

‍

组件

组件的行为与页面类似。通常来说 组件不会自动卸载，而是 随页面一起缓存

组件的生命周期与页面不同，具体生命周期如下：

组件进行到对应节点时便会触发对应的生命周期函数，可以不进行声明，如果不进行声明则不会被触发

注意：小程序的组件的生命周期比页面更精细，具体行为取决于组件的使用方式，有以下几个点需要被注意：

组件不会随页面 onShow() 触发，需要手动更新数据。
使用 wx:if 可以让组件重新创建，从而刷新数据。
使用 hidden 只是隐藏组件，不会销毁。

| 行为 | 页面 onShow() 触发？ | 组件 attached() 触发？ | 组件 detached() 触发？ | | :---------------- | :------------------- | :--------------------- | :--------------------- | | wx.navigateTo() | ✅ | ❌ | ❌ | | wx.navigateBack() | ✅ | ❌ | ❌ | | wx.switchTab() | ✅ | ❌ | ❌ | | wx:if 控制组件 | - | ✅（组件被重新创建） | ✅（组件被销毁） | | hidden 控制组件 | - | ❌ | ❌ |

示例

Component({
  /**
   * 组件的属性列表（外部传入）
   */
  properties: {
    title: {
      type: String,
      value: '默认标题'
    },
    count: {
      type: Number,
      value: 0
    }
  },

  /**
   * 组件的内部数据
   */
  data: {
    innerValue: '内部数据'
  },

  /**
   * 组件的方法列表
   */
  methods: {
    /**
     * 自定义方法 - 增加计数
     */
    increment() {
      this.setData({
        count: this.data.count + 1
      })
      this.triggerEvent('countChanged', { count: this.data.count }) // 触发事件，通知父组件
    },

    /**
     * 自定义方法 - 组件被点击
     */
    handleTap() {
      console.log('组件被点击')
      this.triggerEvent('componentTap', { message: '组件被点击了' })
    }
  },

  /**
   * 组件的生命周期函数
   */
  lifetimes: {
    /**
     * created：组件实例化时触发（在组件未进入页面节点树时）
     */
    created() {
      console.log('组件实例化：created')
    },

    /**
     * attached：组件挂载到页面时触发（类似于页面的 onLoad）
     */
    attached() {
      console.log('组件挂载到页面：attached')
    },

    /**
     * ready：组件视图渲染完成（类似于页面的 onReady）
     */
    ready() {
      console.log('组件视图渲染完成：ready')
    },

    /**
     * moved：组件被移动到其他节点（很少使用）
     */
    moved() {
      console.log('组件被移动：moved')
    },

    /**
     * detached：组件从页面移除时触发（类似于页面的 onUnload）
     */
    detached() {
      console.log('组件被销毁：detached')
    },

    /**
     * error：组件内部发生错误时触发（如 setData 失败）
     */
    error(err) {
      console.error('组件发生错误：', err)
    }
  },

  /**
   * 旧版生命周期（与 lifetimes 功能类似，可兼容旧版小程序）
   */
  pageLifetimes: {
    /**
     * 组件所在的页面显示时触发（类似于 onShow）
     */
    show() {
      console.log('组件所在页面显示：pageLifetimes.show')
    },

    /**
     * 组件所在的页面隐藏时触发（类似于 onHide）
     */
    hide() {
      console.log('组件所在页面隐藏：pageLifetimes.hide')
    },

    /**
     * 组件所在的页面卸载时触发（类似于 onUnload）
     */
    resize(size) {
      console.log('组件所在页面尺寸变化：pageLifetimes.resize', size)
    }
  }
})

‍

组件的写法与页面近乎无二，通常建议将会重复在页面中出现的部分单独写成组件，这样只要在不同的页面中引用即可，页面与组件之间可以相互传递数据

‍

事件绑定

在微信小程序中，事件绑定是页面与用户交互的核心。事件可以绑定到页面元素上，当用户与元素交互时，触发相应的 JavaScript 方法，从而实现预期的操作。

小程序提供了多种事件类型，主要如下：

‍

事件的绑定方式

微信小程序中存在多种事件绑定方式，如下：

在 wxml 中，事件绑定是以 绑定方式+事件类型="js中的函数名"

事件的冒泡

微信小程序的事件分为冒泡事件和非冒泡事件

这些事件会从子组件向父组件传递：

tap（点击）
longpress（长按）
touchstart / touchmove / touchend（触摸）
confirm（键盘回车）

冒泡事件可以理解为，当在 wxml 中，一个视图容器嵌套另一个视图容器的情况下，在点击内部视图容器时，外部容器的对应事件也会被响应，因为本质上内部组件整个本身就是外部组件内部的一部分

以下文为例：

🔹 bindtap="childTap" → 事件会冒泡，父组件的 parentTap() 也会触发
🔹 catchtap="childTap" → 事件不会冒泡，parentTap() 不会触发

<view bindtap="parentTap">
  <view bindtap="childTap" catchtap="childTap">点击我</view>
</view>

Page({
  parentTap(event) {
    console.log('父组件被点击')
  },
  childTap(event) {
    console.log('子组件被点击')
  }
})

事件对象

所有事件都会带一个 event 参数：

handleTap(event) {
  console.log(event);
  // event.currentTarget // 事件绑定的元素
  // event.target // 实际触发事件的元素
  // event.detail // 事件的详细信息（如 `input` 输入的值）
  // event.touches // 当前触摸点
  // event.timeStamp // 事件时间
}

示例：

<view bindtap="handleTap" data-id="123">点击我</view>

handleTap(event) {
  console.log(event.currentTarget.dataset.id); // 输出 "123"
}

绑定事件的元素可以通过 data- 来赋值，在事件方法中可以通过 event.currentTarget.dataset 来获取

即为：如果 WXML 中填写的内容为 <view bindtap="handleTap" data-demo="123">点击我</view> ，那么在 handleTap 方法中就可以通过 event.currentTarget.dataset.demo 来获取值

组件的自定义事件

组件同样支持自定义事件，其事件类型和绑定方式与页面一致。不同之处在于，组件的自定义事件需要在 methods 对象中定义相应的方法。

组件的自定义事件中，可以通过 this.triggerEvent 方法向页面传递数据，如下图所示：

子组件：

<button bindtap="sendData">点击发送</button>

Component({
  methods: {
    sendData() {
      this.triggerEvent('myEvent', { name: '小程序' })
    }
  }
})

父组件：

<custom-component bind:myEvent="handleEvent"></custom-component>

Page({
  handleEvent(event) {
    console.log(event.detail.name) // "小程序"
  }
})

‍

云开发

说实话，云开发这个东西很难说有多好。如果是正儿八经的企业项目，还是建议自备服务器，因为自建服务器能提供更大的后端操作空间，很多逻辑都可以交由后端处理，灵活性更高。

云开发的核心包括 云函数、云存储 和 云数据库：

云函数：支持远程部署 Node.js 代码，并且可以被微信小程序免鉴权直接调用（类似于内网调用，不需要额外考虑安全验证）。
云数据库：提供类 MongoDB 的 NoSQL 数据库，或支持 MySQL。
云存储：用于存储各类文件资源。

从功能上来看，云开发已经具备了基础的服务器端能力，但其中也存在一些非常诡异的软限制。例如，在使用云数据库时，每次查询最多只能返回 20 条数据，想获取更多数据必须通过分页的方式逐步查询。

不过，整体来看，如果只是一个小微项目，为了一个访问量不高的小程序特意准备一台服务器，确实有些浪费。而云开发采用按量计费模式，最低 20 元的套餐就能满足基本需求，相比自建服务器，成本低了不少。所以是否选择云开发，还是要看具体需求，见仁见智。

注意： 使用云开发能力前，需要通过 wx.cloud.init() 进行初始化，一般建议在根目录 app.js 中的 onLaunch 方法中执行一次即可

‍

云存储

上传

在方法中，直接使用 wx.cloud.uploadFile 方法就可以上传文件

cloudPath：文件存储在云端的路径，可以是任意字符串（建议加文件夹结构）。
filePath：本地文件路径，比如 wx.chooseImage() 选择的图片路径。
success：上传成功的回调，res.fileID 是文件的唯一标识，可用于后续访问。

wx.cloud.uploadFile({
  cloudPath: 'example-folder/my-image.png', // 存储路径
  filePath: tempFilePath, // 本地文件路径（通过 wx.chooseImage 获取）
  success: (res) => {
    console.log('上传成功，文件ID：', res.fileID)
  },
  fail: (err) => {
    console.error('上传失败', err)
  }
})

访问或下载

上传成功后，可以通过 fileID 获取文件的临时访问 URL

wx.cloud.getTempFileURL({
  fileList: ['cloud://your-env-id/example-folder/my-image.png'],
  success: (res) => {
    console.log('文件可访问地址：', res.fileList[0].tempFileURL)
  },
  fail: (err) => {
    console.error('获取文件 URL 失败', err)
  }
})

删除文件

如果需要删除云存储中的文件，可以使用 wx.cloud.deleteFile 方法

wx.cloud.deleteFile({
  fileList: ['cloud://your-env-id/example-folder/my-image.png'],
  success: (res) => {
    console.log('删除成功', res.fileList)
  },
  fail: (err) => {
    console.error('删除失败', err)
  }
})

‍

云函数

云函数的核心在于“云端函数”本身，而非小程序的功能。简单来说，可以理解为你在微信云平台上部署了一段 Node.js 代码，并为该云函数指定一个名称。之后，你就可以通过 wx.cloud.callFunction 来调用这个函数了。

大致流程如下：

wx.cloud.callFunction({
  name: 'cloud-name', // 云函数名称
  data: {}, // 传递给云函数的数据
  success: (res) => {
    console.log('云函数返回结果：', res)
  },
  fail: (err) => {
    console.error('云函数调用失败', err)
  }
})

有些聪明的朋友可能会开始纠结：小程序已经可以直接使用云数据库和云存储了，云函数的意义到底在哪儿呢？

其实，云函数的作用非常明显。如果你需要对用户上传的数据进行清洗、计算、合并等复杂操作，或者需要进行云端的高级数据处理，这时候云函数就显得非常有用。直接在客户端进行这些处理可能会加重小程序的负担，而使用云函数可以将这些逻辑封装到云端，从而减轻客户端的计算压力，并提升性能。

另外，如果你是企业主体，可能需要与第三方服务进行集成，比如支付处理、短信发送、邮件服务或社交登录等。这些外部服务通常需要在后端进行操作，而不适合直接在小程序客户端实现。通过云函数，你可以安全地与外部 API 进行交互，并将结果传递回小程序。

最后，如果你有定时任务（例如定期推送消息、清理数据库、生成报告等），云函数也可以在云端定时执行，而不依赖客户端的操作。

云数据库

首先你需要获取数据库实例，通常是通过 wx.cloud.database() 获取：

可以在页面使用数据库时声明，也可以在小程序启动时在 app.js 中注册为全局变量

查询数据

查询数据使用 get() 方法，它返回的是一个 Promise 对象，可以通过 .then() 或 async/await 来获取数据。

const db = wx.cloud.database()
db.collection('users').get({
  success: (res) => {
    console.log('查询结果', res.data) // 返回查询的所有数据
  },
  fail: (err) => {
    console.error('查询失败', err)
  }
})

你也可以根据条件查询数据，微信小程序提供了 db.command 来处理这些操作符，支持如下：

gt()：大于
lt()：小于
gte()：大于等于
lte()：小于等于
eq()：等于
neq()：不等于
in()：在某个数组内
and()：多个条件联合

如果我们想要获取 users 表中 city = '成都' and age > 25 的用户

db.collection('users')
  .where({
    age: db.command.gt(25),
    city: '成都'
  })
  .get({
    success: (res) => {
      console.log('查询结果', res.data)
    },
    fail: (err) => {
      console.error('查询失败', err)
    }
  })

‍

新增数据

在云数据库中插入数据使用 add() 方法。你可以将数据以对象的形式传入，并且云数据库会自动生成 _id, _openid。

const db = wx.cloud.database()
db.collection('users').add({
  data: {
    name: '张三',
    age: 25,
    city: '成都'
  },
  success: (res) => {
    console.log('数据插入成功', res)
  },
  fail: (err) => {
    console.error('数据插入失败', err)
  }
})

‍

更新数据

更新数据使用 update() 方法，可以根据 _id 来指定要更新的文档并修改某些字段的值。

const db = wx.cloud.database()
db.collection('users')
  .doc('文档ID')
  .update({
    data: {
      age: 26
    },
    success: (res) => {
      console.log('数据更新成功', res)
    },
    fail: (err) => {
      console.error('数据更新失败', err)
    }
  })

‍

删除数据

删除数据使用 remove() 方法，删除指定 _id 的数据。

const db = wx.cloud.database()
db.collection('users')
  .doc('文档ID')
  .remove({
    success: (res) => {
      console.log('数据删除成功', res)
    },
    fail: (err) => {
      console.error('数据删除失败', err)
    }
  })

‍

一些小坑

云数据库更多操作可以查看官方文档

云数据库看似很爽，但存在一些很隐蔽的坑，大概如下：

微信云数据库的查询操作默认每次最多返回 20 条数据。如果你想查询更多数据，必须进行分页查询，使用 skip() 和 limit() 进行分页操作。你需要自己控制分页逻辑，每次获取一页数据，直到没有更多数据为止。
云数据库支持的查询条件比较简单，适用于大部分常见的需求，但也有一些限制。比如不支持正则查询，所有的查询都需要通过明确的字段条件进行。无法直接执行 OR 查询，只能通过多个条件查询。复杂的逻辑需要通过多个 where 调用或者在查询后手动合并结果。
云数据库不支持真正的批量写入操作，如批量更新、批量删除等。如果需要进行大量数据的批量处理，可能需要循环处理每一条记录，且会有一定的性能开销。
云数据库采用的是强一致性模型，意味着每次写操作（如 add、update）会确保数据在全局范围内同步一致。如果你需要对数据进行并发写操作（如多人同时修改数据），需要特别注意数据冲突的问题。如果多个用户同时修改同一条数据，可能会出现冲突，云数据库本身不提供冲突解决机制，需要你自己处理相关的业务逻辑。

‍

完成开发后

备案与认证

在微信小程序正式上线前，需要完成备案和认证两个重要步骤。

小程序备案

备案流程共分为三步：

补充小程序基本信息：包括名称、图标、描述等。
设置主营类目：选择小程序所属的业务类别，确保符合微信的运营规范。
提交审核：首先由腾讯进行审核，审核通过后提交至管局进行最终备案。

备案通过后，小程序才具备发布正式版本的资格，否则无法正常对外运营。内容不复杂，个人主体提供下身份证，个人信息，邮箱那些基本就可以了

当天或者第二天腾讯就会打电话过来，不会有太多问题，主要就是核对下个人信息是否准确，询问你姓名，身份证后六位，要审核的小程序名字，他的功能那些

中间突然问了个生肖，估计是为了防止第三方备案

备案主要卡在管局那边，通常需要三五天到一星期，不会对小程序的内容进行审查，因此也可以在开发前进行备案，可以有效节省时间

小程序认证

认证是为了确保小程序主体的合法性和运营合规性。微信会委托 第三方审核机构 对以下内容进行审核：

主体真实性：核验个人或企业的身份信息。
行业资质有效性：检查小程序从事的业务是否符合相关行业要求。
命名合规性：确保小程序名称符合微信命名规则。
线上服务可用性：测试小程序功能是否能正常使用。

个人认证的费用为 30 元，企业认证的费用为 300 元/年。只有通过认证后，小程序才允许被分享和搜索，否则仅能通过扫码或直接访问进行使用。

最后

在微信开发者工具中，开发者可以直接上传代码。上传后，代码会出现在 版本管理 → 开发管理 页面，确认无误后即可提交审核。

在提交审核之前，务必 充分测试 小程序的功能和稳定性。因为 一旦审核通过，代码就可以正式发布（前提是已完成备案/认证）。如果提交了尚未经过完整测试的版本，可能会影响用户体验，甚至导致线上 bug。

审核过程通常较快，一般 1 个工作日内 即可完成。不过需要注意的是，小程序发布后如果在 90 天内未完成备案，将无法继续使用。因此，建议 等备案完成后 再进行正式发布，以免因备案问题影响小程序的正常运营。

至此，从注册微信小程序，到开发、调试，再到 备案与认证，整个流程基本走完了。如果你是第一次开发小程序，可能会觉得过程繁琐，但实际上，微信提供的云开发、开发者工具等已经大大降低了开发门槛，~~虽然微信的文档依然依托答辩~~

当然，技术只是基础，小程序最终能否成功，还是要看产品的价值和用户体验。如果只是想尝试一下小程序开发，那云开发是个不错的选择，能省去服务器的成本和后端开发的麻烦。但如果希望深入发展，还是建议结合自己的需求，考虑是否需要自建后端，或者使用更灵活的技术方案。

使用 Python 合并微信与支付宝账单，生成财务报告

Tue, 21 Jan 2025 15:16:04 GMT

最近用思源笔记记东西上瘾，突然想每个月存一份收支记录进去。但手动整理账单太麻烦了，支付宝导出一份 CSV，微信又导出一份，格式还不一样，每次复制粘贴头都大。

干脆写了个 Python 脚本一键处理，核心就干两件事：

把俩平台的 CSV 账单合并到一起
自动生成带分类表格的 Markdown（直接拖进思源就能渲染）

代码主要折腾了这些：

支付宝账单前 24 行都是废话，直接 skiprows=24 跳过去，GBK 编码差点让我栽跟头
微信账单的列名和支付宝对不上，比如微信叫 交易单号 ，支付宝叫 交易订单号 ，通过 rename 强行对齐
两边金额都有 ¥ 符号和逗号（比如 ¥1,200），用正则 [¥￥,] 替换成数字
最后合并数据时发现微信少几个字段（比如“对方账号”），直接填个 pd.NA 占位

最爽的是生成 Markdown 的部分，pandas 分组统计消费类型，直接 for 循环拼字符串，出来效果长这样：

使用说明

脚本依赖两个 Python 包：pandas 和 chardet。安装方法如下：

pip install pandas chardet

准备账单文件

支付宝账单：
- 打开支付宝 App → 我的 → 账单 → 点击右上角「···」 → 开具交易流水证明 → 用于个人对账
微信账单：
- 打开微信 App → 我的 → 服务 → 钱包 → 账单 → 常见问题 → 下载账单 → 用于个人对账

将这两个文件放到脚本所在的文件夹中。

修改代码底部

# 调用函数读取 CSV 文件并生成新的 CSV 文件
read_csv('支付宝账单路径.csv', '微信账单路径.csv', '生成合并账单路径')
# 调用函数生成 Markdown 文件
generate_markdown('生成合并账单路径.csv', '最终账单.md')

运行脚本，即可得到 最终账单.md

python analysis.py

完整代码（或访问 GitHub 仓库

import pandas as pd

def read_csv(alipay_path, wechat_path, output_path):
    try:
        # 读取 alipay.csv 文件，跳过前 24 行，从第 25 行开始
        alipay = pd.read_csv(alipay_path, skiprows=24, encoding='GBK')

        # 读取 wechat.csv 文件
        wechat = pd.read_csv(wechat_path, skiprows=16)

        # 必需的列名
        required_columns = ['交易订单号', '交易分类', '交易对方', '对方账号', '商品说明', '收/支', '金额', '收/付款方式', '交易状态', '备注', '交易时间']

        # 确保 alipay 数据包含必要的列
        if all(col in alipay.columns for col in required_columns):
            # 选择 alipay.csv 中需要的列
            alipay_selected = alipay[required_columns]
        else:
            print("alipay.csv 文件缺少必要的列。")
            raise ValueError("alipay.csv 列不完整")

        # 重命名 wechat.csv 中的列以匹配 required_columns
        wechat_columns_map = {
            '交易单号': '交易订单号', '交易类型': '交易分类', '商品': '商品说明', '金额(元)': '金额', '支付方式': '收/付款方式', '当前状态': '交易状态'
        }

        # 重命名 wechat 的列
        wechat.rename(columns=wechat_columns_map, inplace=True)

        # 对 wechat.csv 进行列重命名和缺失列填充
        wechat_selected = pd.DataFrame(columns=required_columns)  # 创建一个空的 DataFrame，列名为 required_columns

        # 复制 wechat.csv 中已有的列
        for col in wechat.columns:
            if col in required_columns:
                wechat_selected[col] = wechat[col]

        # 对于 wechat.csv 中没有的列，填充空值（NaN）
        for col in required_columns:
            if col not in wechat_selected.columns:
                wechat_selected[col] = "/"

        # 去掉 '收/支' 列中值为 '不计收支' 的行
        alipay_selected = alipay_selected[alipay_selected['收/支'] != '不计收支']
        wechat_selected = wechat_selected[wechat_selected['收/支'] != '/']

        # 去掉 '金额' 列中的 '¥' 或 '￥' 符号，以及千位分隔符，并转换为浮点数
        wechat_selected['金额'] = wechat_selected['金额'].str.replace(r'[¥￥,]', '', regex=True).astype(float)

        # 为 alipay_selected 和 wechat_selected 添加「分类」列
        alipay_selected['分类'] = '支付宝'
        wechat_selected['分类'] = '微信'

        # 将 alipay 和 wechat 数据合并
        combined_data = pd.concat([alipay_selected, wechat_selected], ignore_index=True)

        # 将合并后的 DataFrame 保存为新的 CSV 文件
        combined_data.to_csv(output_path, index=False)
        print(f"文件已成功保存为 '{output_path}'")
    except FileNotFoundError:
        print("文件未找到，请检查文件路径。")
    except pd.errors.ParserError:
        print("读取 CSV 文件时出现问题，请检查文件格式或编码。")
    except Exception as e:
        print(f"发生错误：{e}")

def generate_markdown(csv_file, output_file):
    # 自动检测文件编码
    import chardet
    with open(csv_file, 'rb') as f:
        result = chardet.detect(f.read())
        encoding = result['encoding']

    # 读取文件
    data = pd.read_csv(csv_file, encoding=encoding)

    # 去除金额列中的符号和千分位逗号，转换为数值型
    data['金额'] = data['金额'].replace({'¥': '', ',': ''}, regex=True).astype(float)

    # 计算本月消费总额和收入总额
    total_expense = data[data['收/支'] == '支出']['金额'].sum()
    total_income = data[data['收/支'] == '收入']['金额'].sum()

    # 计算每个分类的金额
    expense_by_transaction = data[data['收/支'] == '支出'].groupby('交易分类')['金额'].sum().sort_values(ascending=False)
    income_by_transaction = data[data['收/支'] == '收入'].groupby('交易分类')['金额'].sum().sort_values(ascending=False)

    # 计算本月结余
    total_balance = total_income - total_expense

    # 打印调试信息
    print(f"Total Expense: {total_expense}")
    print(f"Total Income: {total_income}")
    print(f"Total Balance: {total_balance}")

    # 生成 markdown 内容
    markdown_content = f"**本月消费总额**：￥{total_expense:.2f}  |  **本月收入总额**：￥{total_income:.2f}  |  **本月结余**：￥{total_balance:.2f}\n\n"


    # 消费类型分析
    markdown_content += "## 消费类型分析 💸\n\n"
    markdown_content += "以下是各消费交易分类与消费金额：\n\n"
    markdown_content += "| 交易分类   | 消费金额   |\n"
    markdown_content += "| ---------- | ---------- |\n"
    for transaction, amount in expense_by_transaction.items():
        markdown_content += f"| {transaction} | ￥{amount:.2f} |\n"

    markdown_content += "\n### 每个交易分类的详细记录：\n"
    for transaction in expense_by_transaction.index:
        markdown_content += f"\n#### {transaction}消费记录 💳\n"
        transaction_data = data[(data['收/支'] == '支出') & (data['交易分类'] == transaction)]
        markdown_content += "| 交易对方  |  金额  | 分类 | 交易时间 |\n"
        markdown_content += "| -------- | ----- | ------ | -------- |\n"
        for _, row in transaction_data.iterrows():
            markdown_content += f"| {row['交易对方']} | ￥{row['金额']:.2f} | {row['分类']} | {row['交易时间']} |\n"

    # 收入类型分析
    markdown_content += "\n## 收入类型分析 💵\n\n"
    markdown_content += "以下是各收入交易分类与收入金额：\n\n"
    markdown_content += "| 交易分类   | 收入金额   |\n"
    markdown_content += "| ---------- | ---------- |\n"
    for transaction, amount in income_by_transaction.items():
        markdown_content += f"| {transaction} | ￥{amount:.2f} |\n"

    markdown_content += "\n### 每个交易分类的详细记录：\n"
    for transaction in income_by_transaction.index:
        markdown_content += f"\n#### {transaction}收入记录 💼\n"
        transaction_data = data[(data['收/支'] == '收入') & (data['交易分类'] == transaction)]
        markdown_content += "| 交易对方  |  金额  | 分类 | 交易时间 |\n"
        markdown_content += "| -------- | ----- | ------ | -------- |\n"
        for _, row in transaction_data.iterrows():
            markdown_content += f"| {row['交易对方']} | ￥{row['金额']:.2f} | {row['分类']} | {row['交易时间']} |\n"

    # 生成收支明细
    markdown_content += "\n## 收支明细\n"
    data_sorted = data.sort_values(by='交易时间')
    markdown_content += "| 交易分类 | 分类 | 收/支 | 金额 | 交易对方 | 商品说明 | 对方账号 | 收/付款方式 | 交易状态 | 备注 | 交易时间 |\n"
    markdown_content += "| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |\n"

    for _, row in data_sorted.iterrows():
        markdown_content += f"| {row['交易分类']} | {row['分类']} | {row['收/支']} | ￥{row['金额']:.2f} | {row['交易对方']} | {row['商品说明']} | {row['对方账号']} | {row['收/付款方式']} | {row['交易状态']} | {row['备注']} | {row['交易时间']} |\n"

    # 保存生成的 markdown 到文件
    with open(output_file, 'w', encoding='utf-8') as f:
        f.write(markdown_content)

    print(f"Markdown 已成功生成并保存为 '{output_file}'")

# 调用示例
# 调用函数读取 CSV 文件并生成新的 CSV 文件
read_csv('./bill/alipay_record_20250201_091025.csv', './bill/微信支付账单(20250101-20250201)——【解压密码可在微信支付公众号查看】.csv', './bill/合并账单.csv')
# 调用函数生成 Markdown 文件
generate_markdown('./bill/合并账单.csv', './bill/账单.md')

一步步教你搭建哔哩哔哩直播机器人与积分商城，轻松部署从零开始

Sat, 28 Dec 2024 02:27:55 GMT

有感觉到文章很乱吗？虽然不知道你怎么想但反正我是有点感觉到了。

不同时间出了好几个教程管理起来真的很麻烦。

我把所有相关的内容放到了一个文档中：点击前往

项目简介

bilibili-danmu不仅能够监控直播间的弹幕进行自动答谢和定时广告推送，还内置了一个积分商城.

用户在直播间开通大航海即可获得积分，并使用积分兑换礼物。

这使得它不仅仅是一个简单的机器人，更是一个可以提升观众互动和增加主播收益的全方位工具。

GitHub 仓库地址：点击进入

视频搭建教程：点击查看

需要准备的工具

阿里云服务器：这是我们将要部署项目的基础环境，费用大约在每月 60 元左右。
FinaShell：一个简便的工具，帮助你连接服务器并进行管理。
Docker：容器化技术，可以轻松部署和管理项目。
Git：用于拉取项目代码，快速获取所需文件。

在接下来的步骤中，我们将详细介绍如何购买服务器、安装必要的工具、部署项目并启动服务。如果你是第一次接触这些内容，也无需担心，本文将一步步为你解释每个细节。

部署说明

1.购买服务器

登录阿里云

前往阿里云控制台。

选择云服务器 ECS

进入左上角菜单，选择云服务器 ECS。

创建实例

付费类型：包年包月

首次使用可以选择 按量付费，按量付费模式下服务器按小时收费，不需要服务器后释放即可，不需要过高的投入长期使用建议包年包月，整体费用会更优惠些
地域：选择香港。

根据工信部规定，国内服务器必须进行备案，否则无法从事互联网信息服务，不过，由于中国设立有特别行政区，采用的法律法规和中国内地有所不同，如香港，使用香港服务器则不用备案
规格：选择 2 核 2G 配置

不低于该配置的情况下可以随意购买，注意：尽量避免购买突发性能实例
系统：选择 Ubuntu 24.04 64 位。
网络：分配 IPv4 地址，按流量付费，带宽速度拉满。

按流量付费时，带宽速度不影响价格，因此访问网站的人不多的情况下可以以较少的费用获得足够速度的网络带宽
登录凭证：选择自定义密码并设置。

购买服务器后登录服务器的密码，建议妥善保管

开放端口

在「云服务器 ECS -> 实例 -> 服务器 -> 安全组」中开放 7777，5177 端口

开启方式见下方视频：

{% dplayer "url=/video/b06795f9/output-13.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

连接服务器

下载并安装 FinaShell（支持跨平台）。

使用 FinaShell 输入服务器 IP 和密码完成连接。

2.安装 docker

获取最新的软件包信息

sudo apt update

{% dplayer "url=/video/b06795f9/output-1.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

安装所有可用的更新

sudo apt upgrade -y

{% dplayer "url=/video/b06795f9/output-2.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

安装 Docker 需要一些必需的依赖包

sudo apt install apt-transport-https ca-certificates curl software-properties-common

{% dplayer "url=/video/b06795f9/output-3.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

添加 Docker 官方的 GPG 密钥

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

{% dplayer "url=/video/b06795f9/output-4.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

将 Docker 官方的仓库添加到 APT 源中

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

{% dplayer "url=/video/b06795f9/output-5.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

更新本地包索引。

sudo apt update

{% dplayer "url=/video/b06795f9/output-6.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

安装 Docker

sudo apt install docker-ce docker-ce-cli containerd.io docker-compose

{% dplayer "url=/video/b06795f9/output-7.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

确保 Docker 服务正在运行

sudo systemctl start docker

{% dplayer "url=/video/b06795f9/output-8.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

设置 Docker 开机自启

sudo systemctl enable docker

{% dplayer "url=/video/b06795f9/output-9.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

你可以通过运行以下命令来验证 Docker 是否已正确安装：

sudo docker --version

输出应该显示类似以下的版本信息

Docker version 27.4.1, build b9d17ea

3.部署项目

克隆项目

git clone https://github.com/zxc7563598/php-bilibili-danmu-docker.git /opt/bilibili-robots

{% dplayer "url=/video/b06795f9/output-10.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

前往目录

cd /opt/bilibili-robots

{% dplayer "url=/video/b06795f9/output-11.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

执行初始化脚本

sh ./setup.sh

{% dplayer "url=/video/b06795f9/output-12.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

构建 docker

docker-compose build

启动 docker

docker-compose up -d

正常使用

机器人的地址为：http://您服务器 IP:7777

首次登录会要求需要输入账号密码，输入后后续访问均需要通过本次输入的账号密码进行访问，请妥善保存

启用积分商城

前往机器人后台 http://您服务器IP:7777
进入积分商城
进入系统配置
点击 构建商城 获取商城地址

{% dplayer "url=/video/b06795f9/output-14.mp4" "loop=no" "theme=#FADFA3" "autoplay=false" "screenshot=true" "hotkey=true" "preload=false" "volume=0.9" "playbackSpeed=1" "lang=zh-cn" "mutex=true" %}

常见问题

为什么要购买香港的服务器？

docker 的环境，docker 安装后的镜像以及项目均托管在外网，使用国内地区的服务器时需要解决科学上网的问题
根据工信部规定，国内服务器必须进行备案，否则无法从事互联网信息服务，使用国内地区的服务器需要绑定域名时要对域名进行备案

使用香港服务器会出现哪些问题？

阿里云提供的香港服务器有独立回国的线路，因此基本不会存在问题

但偶尔也会存在部分用户访问不到的情况，通常片刻后恢复正常，只不过相对国内服务器还是存在一点稳定性差异

如何绑定域名？

在阿里云或 Godaddy 等域名交易平台可以 注册/购买 域名。

域名购买，解析到您开通的服务器 IP 后，通过 Finalshell 连接服务器后执行以下内容：

1.获取最新的软件包信息

sudo apt update

2.安装 nginx

sudo apt install nginx

3.在 /etc/nginx/conf.d 目录创建一个.conf 文件（比如域名是 xxx.com 配置文件就叫 xxx.com.conf）文件内容如下：

server {
    listen 80;
    server_name 机器人控制台域名;

    location / {
        proxy_pass http://localhost:7777;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
server {
    listen 80;
    server_name 积分商城域名;

    location / {
        proxy_pass http://localhost:5177;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

4.检查 nginx 配置是否正确

sudo nginx -t

5.重启 nginx

sudo systemctl reload nginx

6.安装 certbot

sudo apt install certbot python3-certbot-nginx

7.申请配置证书

sudo certbot --nginx -d 域名

8.修改配置修改 项目地址 与 商城地址 后下拉到底部进行保存

积分商城 -> 系统配置">

暂时想不到其他问题了，想起来再说

用 Python 批量插入图片到 Word 文档 —— 解放双手的利器

Tue, 10 Dec 2024 07:24:45 GMT

最近在整理一堆截图资料，需要把几万张截图整理到 Word 文档中打印，实在是让人头大。

这些截图每行放 3 张，每页 6 张，这要是创建表格然后一张一张往里面放的话大概弄到猴年马月都搞不完。

于是决定写个小脚本来自动化处理这件事，以便节省时间摸鱼。

于是就有了这个小脚本，简单易懂，关键是能用！废话不多说，直接上代码，接着再讲讲实现逻辑。

from docx import Document
from docx.shared import Inches
import os

# 图片文件夹路径
img_folder = "/user/path"  # 换成你存图片的路径
img_files = sorted([f for f in os.listdir(img_folder) if f.endswith(('.jpg', '.png'))])

# 创建 Word 文档
doc = Document()

# 设置图片宽度（单位是英寸）
image_width = 4.7 / 2.54  # 把 4.7 厘米转换成英寸，Word里是用英寸单位的

# 每行插入 3 张图片
images_per_row = 3

# 当前插入图片的计数器
count = 0

# 循环插入图片
for i, img in enumerate(img_files):
    # 如果是新的一行，就创建一行表格
    if count % images_per_row == 0:
        row = doc.add_table(rows=1, cols=images_per_row).rows[0]

    # 插入图片到当前表格单元格
    cell = row.cells[count % images_per_row]
    run = cell.paragraphs[0].add_run()
    run.add_picture(os.path.join(img_folder, img), width=Inches(image_width))

    # 图片计数器加 1
    count += 1

    # 每插入 6 张图片，就分页
    if (i + 1) % 6 == 0:
        doc.add_page_break()

# 保存文档
output_path = "/user/path/name.docx"  # 换成你的保存路径
doc.save(output_path)

print(f"文档已生成：{output_path}")

脚本逻辑

整个脚本可以简单分成几个步骤：

准备好图片

先把需要处理的图片放到一个文件夹里，比如 /user/path。脚本会扫描这个文件夹，只找扩展名是 .jpg 或 .png 的图片，还会自动按文件名排序，方便后续插入时保持顺序。

创建 Word 文档

我们用 python-docx 库来处理 Word 文档，开始时是空白的，后续所有内容都是动态插入的。

通过 pip install python-docx 安装库

循环插入图片

表格布局：每行 3 张图片，用表格实现排版，每张图片放在一个表格单元格里。
图片宽度：为保持美观，设置每张图片的宽度为 4.7 厘米（脚本里转成了英寸）。
分页：每插入 6 张图片，自动插入一个分页符，让文档看起来更加规整。

保存文档

生成的 Word 文件会保存到指定路径，直接打开就能看到排版整齐的图片文档啦！

效果展示

完成后的文档每行有 3 张图片，整齐美观。6 张图片一页，自动分页，特别适合整理大批量截图。以下是文档排版的示意：

---

## | 图 1 | 图 2 | 图 3 |

## | 图 4 | 图 5 | 图 6 |

## （分页）

## | 图 7 | 图 8 | 图 9 |

为什么要用这个脚本？

我之前也尝试过手动插入，但拖来拖去太费劲，还经常对不齐。有了这个脚本，直接运行一下，几万张图片轻松搞定。更重要的是，万一后续需求变了，比如每行插 4 张、分页规则不同，只需要稍微改动代码就行，效率提升不是一点点！

从零开始：如何创建和启动 Docker 容器

Sun, 01 Dec 2024 10:10:57 GMT

最近我做了一个哔哩哔哩直播弹幕姬项目，为了让大家能更方便地使用，我决定将这个项目容器化，直接用 Docker 一键启动。这样，别人就不用担心配置环境了，直接运行就好。

如果你对 Docker 还不太熟悉，它其实就是一个让你把应用和所有的依赖打包在一起的工具，确保在任何机器上都能以相同的方式运行。通过 Docker，我能把项目打包成容器，避免了不同环境配置不一致的问题。

接下来，我会一步步带你走过：

如何写 Dockerfile 来创建镜像；
用 docker-compose.yml 来管理多个容器；
怎么构建并启动 Docker 容器；
容器里的应用怎么配置和运行；
如果需要扩展容器环境，应该怎么做。

不管你是刚接触 Docker 还是已经有点经验，相信这篇教程能帮你更好地理解 Docker，并能把自己的项目轻松容器化。

创建 Dockerfile

Dockerfile 是一个文本文件，包含了一系列的指令，Docker 使用这些指令来构建镜像。你可以通过它指定操作系统、安装依赖、复制文件、设置环境变量等。

示例 Dockerfile

FROM php:8.2-cli-alpine

# 安装 Composer
COPY --from=composer:2.7 /usr/bin/composer /usr/bin/composer

# 设置环境变量
ENV TZ=Asia/Shanghai

# 更新软件包列表并安装系统依赖
RUN apk update && apk add --no-cache \
    bash \
    git \
    curl \
    brotli \
    build-base \
    autoconf \
    libtool \
    make \
    linux-headers \
    pcre-dev \
    libevent \
    libevent-dev \
    libpng-dev \
    libjpeg-turbo-dev \
    libwebp-dev \
    freetype-dev \
    $PHPIZE_DEPS \
    redis \
    busybox-suid  # 添加 cron 支持

# 安装 PHP 扩展
RUN docker-php-ext-install pdo_mysql pcntl

# 安装 PHP GD 扩展
RUN docker-php-ext-configure gd \
    --with-jpeg \
    --with-webp \
    --with-freetype \
    && docker-php-ext-install gd

# 安装 PHP Redis 扩展
RUN pecl install redis \
    && docker-php-ext-enable redis

# 安装 PHP Brotli 扩展
RUN pecl install brotli \
    && docker-php-ext-enable brotli

# 设置工作目录
WORKDIR /var/www/bilibili_danmu

# 复制项目文件到容器中
RUN git clone https://github.com/zxc7563598/php-bilibili-danmu.git /var/www/bilibili_danmu

# 安装 PHP 依赖（生产环境中使用 --no-dev）
RUN composer install

# 设置目录权限
RUN chmod +x /var/www/bilibili_danmu

# 添加 cron 任务
RUN echo "0 * * * * /var/www/bilibili_danmu/check_and_update.sh" > /etc/crontabs/root

说明： FROM：指定基础镜像。 RUN：安装依赖和 PHP 扩展。 COPY：将本地文件复制到容器中。 WORKDIR：设置工作目录。 CMD：容器启动时执行的命令。

创建 Docker Compose 文件

docker-compose.yml 文件定义了多个容器的服务、网络和卷。它让我们可以一键启动多个容器，而不需要手动启动每个容器。

示例 docker-compose.yml

services:
  php:
    build: .
    container_name: php
    command: sh -c "sh setup.sh && php start.php start -d && crond && tail -f /dev/null"
    volumes:
      - /var/www/bilibili_danmu
    networks:
      - webnet
    expose:
      - '7776'

  nginx:
    image: nginx:latest
    container_name: nginx
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf
      - .:/var/www/bilibili_danmu
    ports:
      - '7777:80'
    networks:
      - webnet
    depends_on:
      - php

  redis:
    image: redis:latest
    container_name: redis
    ports:
      - '6379'
    networks:
      - webnet

networks:
  webnet:
    driver: bridge

在上述文件中，定义了三个服务：php、nginx 和 redis，并配置了它们如何协同工作：

PHP 服务：运行应用代码并启动 PHP 和 cron 服务。

Nginx 服务：提供 Web 访问，使用自定义配置文件。

Redis 服务：提供缓存支持。

所有这些服务都连接到同一个自定义网络 webnet，确保它们能够顺畅地通信。

可以通过运行 docker-compose up -d 来启动这些服务，并在浏览器中访问 Nginx 提供的 Web 服务。

PHP 服务

php:
  build: .
  container_name: php
  command: sh -c "sh setup.sh && php start.php start -d && crond && tail -f /dev/null"
  volumes:
    - /var/www/bilibili_danmu
  networks:
    - webnet
  expose:
    - '7776'

build: .：这行代码表示 Docker 会在当前目录下查找 Dockerfile 并基于它构建 PHP 镜像。这个镜像包含了运行 PHP 应用所需的所有依赖和配置。
container_name: php：为这个容器指定一个名字，便于我们在 Docker 中识别和管理。
command: sh -c "sh setup.sh && php start.php start -d && crond && tail -f /dev/null"：这行命令会在容器启动时执行。首先，它会运行 setup.sh 脚本，接着启动 PHP 应用（start.php start -d），然后启动 cron 服务（crond），最后使用 tail -f /dev/null 保持容器处于运行状态，防止容器因任务执行完毕而停止。
volumes：

volumes:
  - /var/www/bilibili_danmu

这行代码将宿主机的 /var/www/bilibili_danmu 目录挂载到容器内部的 /var/www/bilibili_danmu 目录。这确保了 PHP 容器能够访问和处理项目代码。

networks：

networks:
  - webnet

容器会连接到一个名为 webnet 的网络，这个网络在文件底部定义。

expose：

expose:
  - '7776'

expose 命令暴露容器的 7776 端口，供其他容器（如 Nginx）访问。需要注意的是，expose 并不会将端口映射到宿主机，只是让其他容器可以通过这个端口访问。

Nginx 服务

nginx:
  image: nginx:latest
  container_name: nginx
  volumes:
    - ./nginx/default.conf:/etc/nginx/conf.d/default.conf
    - .:/var/www/bilibili_danmu
  ports:
    - '7777:80'
  networks:
    - webnet
  depends_on:
    - php

image: nginx:latest：使用官方的 Nginx 镜像，并始终拉取最新版本。
container_name: nginx：

为 Nginx 容器指定一个名字，便于识别。

volumes：

volumes:
  - ./nginx/default.conf:/etc/nginx/conf.d/default.conf
  - .:/var/www/bilibili_danmu

这两个挂载使得宿主机的 ./nginx/default.conf 配置文件和整个项目目录能够映射到容器内。这样，Nginx 容器就能使用项目的代码和自定义的配置文件。

ports：

ports:
  - '7777:80'

这行代码将容器的 80 端口映射到宿主机的 7777 端口，允许外部访问 Nginx 服务。

networks：

networks:
  - webnet

Nginx 服务也连接到 webnet 网络，以便和其他容器通信。

depends_on：

depends_on:
  - php

这表示 Nginx 容器在启动时依赖于 php 容器。depends_on 确保 PHP 容器先启动，以便 Nginx 容器能够访问它。

Redis 服务

redis:
  image: redis:latest
  container_name: redis
  ports:
    - '6379'
  networks:
    - webnet

image: redis:latest：使用官方 Redis 镜像，拉取最新版本。

container_name: redis：为 Redis 容器指定一个名字，便于管理和识别。

ports：

ports:
  - '6379'

将 Redis 的默认端口 6379 暴露到宿主机上，允许外部程序与 Redis 通信。

networks：

networks:
  - webnet

Redis 容器连接到 webnet 网络，确保它与 PHP 和 Nginx 容器能够通信。

自定义网络定义

networks:
  webnet:
    driver: bridge

networks 定义了一个名为 webnet 的网络，所有容器都将连接到这个网络。通过这种方式，容器间可以互相通信，并且不会暴露给外部世界，除非明确映射端口。这里使用了 bridge 网络驱动，这是 Docker 默认的网络类型，适合容器之间的通信。

构建和启动容器

构建 Docker 镜像：在包含 Dockerfile 与 docker-compose.yml 的目录下运行以下命令构建镜像：

docker-compose build

启动 Docker Compose 服务：在包含 Dockerfile 与 docker-compose.yml 的目录下运行：

docker-compose up -d

这条命令会构建和启动所有定义的服务。-d 参数表示在后台运行。

查看容器状态：使用以下命令查看运行中的容器：

docker ps

停止容器：要停止容器，运行以下命令：

docker-compose down

其他常用命令

查看容器日志：

docker logs <container_name_or_id>

进入容器的终端：

docker exec -it <container_name_or_id> sh

删除容器和镜像：停止并删除所有容器和镜像：

docker-compose down --rmi all

删除不再使用的资源

以下内容均会被删除：

所有未被任何容器使用的镜像（dangling images）
所有停止的容器（stopped containers）
所有未被使用的网络（unused networks）
所有未被使用的卷（未使用的匿名卷，需加 --volumes 才会删除）
所有未使用的构建缓存

docker system prune

从手动到自动：使用 Puppeteer 高效截取大量网页截图

Sun, 03 Nov 2024 02:15:38 GMT

最近生活出了那么一点小问题。给老板做了套系统，老板拿着去做小额贷款犯法了。所以我也是被警方控制协助调查，这下真从面向对象变成面向监狱了。不过还好，因为积极配合，问题不大。

但事情远未结束。警方要求我取证，把所有后台页面都截成图。零零散散算下来，大约有 20 万张截图。这要是手动来得干几个月都说不定。于是，我开始寻求能救命的自动化工具，这时，我发现了 Puppeteer。

发现 Puppeteer

Puppeteer 是一个由 Google 开发的 Node.js 库，它为控制无头浏览器（如 Chromium）提供了简单的 API。它不仅支持网页截图，还可以执行各种其他任务，比如网页爬虫、自动化表单提交和生成 PDF 等。

Puppeteer 入门

要开始使用 Puppeteer，只需几个简单的步骤：

安装 Puppeteer：

    npm install puppeteer

编写基础代码

下面是一个基础的 Puppeteer 脚本，用于打开一个网页并截取截图：

const puppeteer = require('puppeteer')

;(async () => {
  const browser = await puppeteer.launch()
  const page = await browser.newPage()
  await page.goto('https://example.com')
  await page.screenshot({ path: 'example.png' })
  await browser.close()
})()

运行这个脚本后，你将在项目目录中看到访问 https://example.com 后截取到的截图文件 example.png

最终实现

使用 Puppeteer 启动一个无头浏览器来打开特定 URL，并针对不同的 tag 进行多次抓取，每个抓取过程限速 5 个并行任务
为每个 data 项创建一个路径并将截图保存到该路径下。
为不同的 tag 设定了不同的加载延迟时间。

const puppeteer = require('puppeteer');
const fs = require('fs');
const path = require('path');

(async () => {
    const pLimit = (await import('p-limit')).default;
    const limit = pLimit(5);
    const browser = await puppeteer.launch({
        args: ['--no-sandbox', '--disable-setuid-sandbox']
    });
    // 要抓取的页面参数信息
    const data = [
        { id: 16212, path: "对应文件夹" },
        { id: 16229, path: "对应文件夹" },
        { id: 16591, path: "对应文件夹" }
    ];
    // 要抓取的页面标签
    const tags = [
        'customer',
        'contact',
        'address_book',
        'sms',
        'wind_control',
        'orders'
    ];
    // 网页要设置的cookie
    const cookies = [
        { name: 'token', value: 'xxxxxx', domain: '' },
    ];
    // 每个页面标签延迟抓取的毫秒时间
    const delays = {
        customer: 3000,
        contact: 10000,
        address_book: 3000,
        sms: 5000,
        wind_control: 2000,
        orders: 2000
    };
    // 开始处理
    for (const item of data) {
        const dirPath = path.join(__dirname, '项目名称', item.path);
        if (!fs.existsSync(dirPath)) {
            fs.mkdirSync(dirPath, { recursive: true });
        }

        const screenshotPromises = tags.map(tag =>
            limit(async () => {
                const url = `http://baseurl/${tag}?borrow_id=${item.id}`;
                const page = await browser.newPage();
                try {
                    // 设置截图的分辨率
                    await page.setViewport({ width: 1920, height: 1080 });
                    // 设置cookie
                    await page.setCookie(...cookies);
                    // 设置导航到指定 url 并等待页面加载完成，直到满足特定的网络状态条件
                    // 通常为：至少有 500 毫秒的时间内，网络连接不超过 2 个
                    await page.goto(url, { waitUntil: 'networkidle2' });
                    // 对应标签暂停一段时间，以便网页动画加载完成
                    await page.waitForTimeout(delays[tag]);
                    // 拼接存储路径
                    const screenshotPath = path.join(dirPath, ${tag}.png);
                    // 存储截图
                    await page.screenshot({ path: screenshotPath });
                    console.log(`${screenshotPath}:存储成功`);
                } catch (error) {
                    console.error(`${screenshotPath}:存储失败`, error);
                } finally {
                    // 关闭页面
                    await page.close();
                }
            })
        );

        await Promise.all(screenshotPromises);
    }
    // 关闭浏览器
    await browser.close();
})();

结论

使用 Puppeteer 后，曾经需要手动完成的长时间截图任务现在只需短短几分钟或几小时就能搞定。如果你也有类似需求，试试 Puppeteer，相信它会成为你高效工作的利器。

Bilibili直播信息流：连接方法与数据解析

Tue, 29 Oct 2024 03:26:34 GMT

如今，市面上已经有不少开源项目可以用于连接 B 站直播 WebSocket 获取信息流。

但在实际使用中，常常发现它们并不能完全满足个性化需求。

为了更好地适配自己的业务场景，我决定自己动手实现一套连接方案。

因此，我整理了整个实现过程的一些关键步骤和注意事项，希望能够对有相似需求的朋友们有所帮助

接入前准备

获取直播间真实 ID

网页版直播间 URL 携带的房间号可能是短号，并不保证一定为真实地址，因此建议调用该接口以确保房间号无误

请求方式：GET

请求地址：https://api.live.bilibili.com/room/v1/Room/get_info

| 参数名 | 类型 | 内容 | | :------ | :--- | :-------- | | room_id | int | 直播间 ID |

请求响应示例与字段说明

curl -G 'https://api.live.bilibili.com/room/v1/Room/get_info' \
--data-urlencode 'room_id=27668995'

{
  "code": 0,
  "msg": "ok",
  "message": "ok",
  "data": {
    "uid": 3493124609411229, // 主播id
    "room_id": 27668995, // 真实房间id
    "short_id": 0, // 直播间短号，0为无短号
    "attention": 13353, // 关注数量
    "online": 4173, // 观看人数
    "is_portrait": false, // 是否是竖屏
    "description": "一只屑狐狸，不专业的CV，新晋歌杂，不缺席你的每一天...直播时间： 晚22:00-02:00，下午3:00-7:00闪现打游戏", // 描述
    "live_status": 1, // 直播间状态：0-未开播，1-直播中，2-轮播中
    "area_id": 371, // 分区id
    "parent_area_id": 9, // 父分区id
    "parent_area_name": "虚拟主播", // 父分区名称
    "old_area_id": 6, // 旧版分区id
    "background": "", // 背景图片链接
    "title": "不给糖就捣蛋", // 标题
    "user_cover": "https://i0.hdslb.com/bfs/live/new_room_cover/22426f0ead9804fabd06ad1c4305e2641a4e6d11.jpg", // 封面
    "keyframe": "https://i0.hdslb.com/bfs/live-key-frame/keyframe11011431000027668995752wsi.jpg", // 关键帧
    "is_strict_room": false, // 待观测
    "live_time": "2024-11-01 14:25:09", // 开播时间
    "tags": "御姐,屑狐狸,狐仙,憨憨,温柔", // 标签
    "is_anchor": 0, // 待观测
    "room_silent_type": "", // 禁言状态
    "room_silent_level": 0, // 禁言等级
    "room_silent_second": 0, // 禁言等级（单位秒）
    "area_name": "虚拟日常", // 分区名称
    "pendants": "", // 待观测
    "area_pendants": "", // 待观测
    "hot_words": [
      "2333333",
      "喂，妖妖零吗",
      "红红火火恍恍惚惚",
      "FFFFFFFFFF",
      "Yooooooo",
      "啪啪啪啪啪",
      "666666666",
      "老司机带带我",
      "你为什么这么熟练啊",
      "gg",
      "prprpr",
      "向大佬低头",
      "请大家注意弹幕礼仪哦！",
      "还有这种操作！",
      "囍",
      "打call",
      "你气不气？",
      "队友呢？"
    ], // 热词
    "hot_words_status": 0, // 热词状态
    "verify": "", // 待观测
    "new_pendants": {
      // 头像框
      "frame": {
        // 头像框信息
        "name": "大乱斗乱斗之王", // 名称
        "value": "https://i0.hdslb.com/bfs/live/fc28a2a4123154012e0ce3da1273de5f17e81b24.png", // 头像框图片URL
        "position": 0, // 位置
        "desc": "", // 描述
        "area": 0, // 分区
        "area_old": 0, // 旧分区
        "bg_color": "", // 背景色
        "bg_pic": "", // 背景图
        "use_old_area": false // 是否旧分区号
      },
      "badge": {
        // 大V才会有的信息
        "name": "v_person", // 认证类型：v_person=个人认证(黄)，v_company=企业认证(蓝)
        "position": 3, // 位置，可能是个枚举
        "value": "", // 待观测
        "desc": "bilibili 知名UP主、直播高能主播" // 描述
      },
      "mobile_frame": {
        // 头像框信息，手机版，可能为null
        "name": "大乱斗乱斗之王", // 名称
        "value": "https://i0.hdslb.com/bfs/live/fc28a2a4123154012e0ce3da1273de5f17e81b24.png", // 头像框图片URL
        "position": 0, // 位置
        "desc": "", // 描述
        "area": 0, // 分区
        "area_old": 0, // 旧分区
        "bg_color": "", // 背景色
        "bg_pic": "", // 背景图
        "use_old_area": false // 是否旧分区号
      },
      "mobile_badge": {
        // 大V才会有的信息，手机版，可能为null
        "name": "v_person", // 认证类型：v_person=个人认证(黄)，v_company=企业认证(蓝)
        "position": 3, // 位置，可能是个枚举
        "value": "", // 待观测
        "desc": "bilibili 知名UP主、直播高能主播" // 描述
      }
    },
    "up_session": "557568462506308099", // 待观测
    "pk_status": 0, // pk状态
    "pk_id": 0, // pk id
    "battle_id": 0, // 待观测
    "allow_change_area_time": 0, // 待观测
    "allow_upload_cover_time": 0, // 待观测
    "studio_info": {
      // 待观测
      "status": 0, // 待观测
      "master_list": []
    }
  }
}

获取信息流认证秘钥

该接口可以获取到对应直播间信息流的链接地址，以及建立链接需要认证的 token 信息

注意： B 站更新了隐私政策, 连接建立 5 分钟左右, 若该连接认证时传入信息来自未登录用户, 会提示 为保护用户隐私，未注册登陆用户将无法查看他人昵称, 随后所有发送弹幕的用户 id 都为 0, 用户名部分也使用 * 保护，因此调用本接口时需要传递 ** cookie **

注意： ws 与 wss 连接地址带有路径 /sub, 如 wss://tx-sh-live-comet-08.chat.bilibili.com:443/sub

请求方式：GET

请求地址：https://api.live.bilibili.com/xlive/web-room/v1/index/getDanmuInfo

| 参数名 | 类型 | 内容 | | :----- | :--- | :------------ | | id | int | 直播间真实 id |

请求响应示例与字段说明

curl -G 'https://api.live.bilibili.com/xlive/web-room/v1/index/getDanmuInfo' \
--data-urlencode 'id=30118851'

{
  "code": 0, // 0：成功，65530：token错误（登录错误），1：错误，60009：分区不存在，其他错误仍需观察
  "message": "0", // 错误信息
  "ttl": 1, // 默认为1
  "data": {
    // 信息本体
    "group": "live", // 不重要，默认live
    "business_id": 0, // 不重要，默认 0
    "refresh_row_factor": 0.125, // 不重要，默认0.125
    "refresh_rate": 100, // 不重要，默认100
    "max_delay": 5000, // 不重要，默认5000
    "token": "TrF6FaSlmxVBM4eBYGoaWPuZ-xVL-bhK80waLbGRfpj6JiLkjgaxLcu5whFM6iEBrQFw8wJwdraBJwkctMzMrkyP7kmWkRAmFUa_Z1aiXVDhyMwsiQe81KHMGC82tuyWF9iHNstIX-M0IhU=", // 认证密钥
    "host_list": [
      // 信息流服务器节点列表
      {
        "host": "tx-sh-live-comet-08.chat.bilibili.com", // 服务器域名
        "port": 2243, // tcp端口
        "wss_port": 443, // wss 端口
        "ws_port": 2244 // ws端口
      },
      {
        "host": "tx-bj-live-comet-08.chat.bilibili.com",
        "port": 2243,
        "wss_port": 443,
        "ws_port": 2244
      },
      {
        "host": "broadcastlv.chat.bilibili.com",
        "port": 2243,
        "wss_port": 443,
        "ws_port": 2244
      }
    ]
  }
}

信息流接入

数据包为 MQ（Message Queue，消息队列）使用 Websocket 或 TCP 连接作为通道，具体格式为 弹幕协议 + 正文数据

操作流程：

连接信息流服务器节点 -> 发送认证包 -> 接收认证包回应 -> 接收普通包&（每 30 秒发送心跳包 -> 接收心跳回应）

Packet Length：整个 Packet 的长度，包含 Header
Header Length：Header 的长度，固定为 16
Version：协议版本
Operation：操作码
Sequence ID：保留字段，可以忽略
Body：消息体，客户端解析 Body 之前请先解析 Version 字段

Version 说明： 0 - 普通包正文不使用压缩 1 - 心跳及认证包正文不使用压缩 2 - 普通包(zlib 压缩) 3 - 普通包(brotli 压缩)

Operation 说明： 2 - 客户端发送的心跳包(30 秒发送一次) 3 - 服务器收到心跳包的回复 5 - 服务器推送的弹幕消息包 7 - 客户端发送的鉴权包(客户端发送的第一个包) 8 - 服务器收到鉴权包后的回复

注意：B 站最近加强了风控，建议在建立连接时携带好用户的cookie以避免风控限流

认证包构建

注意: 认证包需要在握手成功 5 秒内发送, 否则强制断开连接

认证包头部信息基于上述协议格式不再赘述，仅说明 Body 如何构建

| 字段 | 类型 | 说明 | | :------- | :----- | :------------------------------------------ | | uid | int | 用户 uid | | roomid | int | 主播房间 id | | protover | int | 协议版本，决定了后续数据包的 Version | | buvid | string | 用户buvid3，可在cookie中获得 | | platform | string | 平台，传web即可 | | type | int | 不确定用途，目前 B 站网页版传 2，照着传即可 | | key | string | 获取信息流认证秘钥接口提供的token |

protover 说明： 2 - 后续正文以 zlib 方式返回 3 - 后续正文以 brotli 方式返回

示例：

00000000: 0000 0152 0010 0001 0000 0007 0000 0001  ...R............
00000001: 7b22 7569 6422 3a34 3332 3530 3531 2c22  {"uid":4325051,"
00000002: 726f 6f6d 6964 223a 3331 3432 3735 3432  roomid":31427542
00000003: 2c22 7072 6f74 6f76 6572 223a 332c 2262  ,"protover":3,"b
00000004: 7576 6964 223a 2232 4445 3846 4141 312d  uvid":"2DE8FAA1-
00000005: 3642 4643 2d45 3741 412d 3031 3041 2d31  6BFC-E7AA-010A-1
00000006: 3039 4544 3039 3443 4245 3537 3935 3139  09ED094CBE579519
00000007: 696e 666f 6322 2c22 706c 6174 666f 726d  infoc","platform
00000008: 223a 2277 6562 222c 2274 7970 6522 3a32  ":"web","type":2
00000009: 2c22 6b65 7922 3a22 375f 6573 4f70 564e  ,"key":"7_esOpVN
0000000a: 697a 5570 4732 7069 3169 7741 2d79 3651  izUpG2pi1iwA-y6Q
0000000b: 4545 4550 734a 7872 666a 6c4c 5f73 4e50  EEEPsJxrfjlL_sNP
0000000c: 6b77 4f55 385a 7255 4150 334a 7951 746e  kwOU8ZrUAP3JyQtn
0000000d: 4154 6748 474c 645f 514a 616b 794b 4d54  ATgHGLd_QJakyKMT
0000000e: 4b75 717a 3856 5174 6474 5479 5f75 476c  Kuqz8VQtdtTy_uGl
0000000f: 5541 3958 6d75 334f 507a 6944 5170 3952  UA9Xmu3OPziDQp9R
00000010: 5832 6f57 4366 5356 3345 7778 3554 4532  X2oWCfSV3Ewx5TE2
00000011: 6c6a 4552 616e 684f 3757 7230 695f 3641  ljERanhO7Wr0i_6A
00000012: 584f 3862 6d38 634f 5757 5649 4a31 7966  XO8bm8cOWWVIJ1yf
00000013: 5535 4c63 7638 484b 3864 564e 4954 6e74  U5Lcv8HK8dVNITnt
00000014: 7144 4669 7339 5471 586d 544f 344e 413d  qDFis9TqXmTO4NA=
00000015: 227d                                     "}

命令列表

SEND_GIFT：赠送礼物
DANMU_MSG：弹幕信息
GUARD_BUY：开通舰长
GUARD_LOTTERY_START：千舰推送
USER_TOAST_MSG：上舰抽奖消息推送
SUPER_CHAT_MESSAGE：醒目留言
ENTRY_EFFECT：舰长进入直播间（进入直播间特效）
INTERACT_WORD：直播间互动
PK_BATTLE_PRE_NEW：PK 即将开始

命令说明

赠送礼物:SEND_GIFT

{
  "cmd": "SEND_GIFT", // 固定命令
  "data": {
    // 数据信息
    "action": "投喂", // 行为，一般都是投喂
    "bag_gift": {
      // 从背包中赠送礼物时会出现
      "price_for_show": 500, // 礼品单价(电池*100)
      "show_price": 1 // 赠送数量
    },
    "batch_combo_id": "30d6eb24-88c5-49bf-9023-baa91ec084a7", // 连击ID
    "batch_combo_send": {
      // 连击信息
      "action": "投喂", // 行为，一般都是投喂
      "batch_combo_id": "30d6eb24-88c5-49bf-9023-baa91ec084a7", // 连击ID
      "batch_combo_num": 1, // 当前连击数
      "blind_gift": {
        // 相关礼物信息
        "blind_gift_config_id": 51, // 赠送盲盒时存在数据，疑似是盲盒的配置
        "from": 0, // 不确定用途，观测到 blind_gift_config_id 存在时为0，其余情况无数据
        "gift_action": "爆出", // 赠送盲盒时为爆出，其余无数据
        "gift_tip_price": 16000, // 赠送盲盒时为爆出的礼物价格，其余无数据
        "original_gift_id": 32251, // 赠送盲盒时为盲盒的 gift_id，其余无数据
        "original_gift_name": "心动盲盒", // 赠送盲盒时为盲盒的名称，其余无数据
        "original_gift_price": 15000 // 赠送盲盒时为盲盒的价格，其余无数据
      },
      "gift_id": 32128, // 礼物id，如果是盲盒则为盲盒爆出的礼物id
      "gift_name": "爱心抱枕", // 礼物名称，如果是盲盒则为盲盒爆出的礼物名称
      "gift_num": 1, // 赠送数量
      "send_master": null, // 不清楚用途
      "uid": 3494362281412802, // 赠送人uid
      "uname": "舒葵交错" // 赠送人名称
    },
    "beatId": "", // 暂不确定用途，观测到多是空或者0
    "biz_source": "live", // 暂不确定用途，观测到多是 Live 跟 live
    "blind_gift": {
      // 相关礼物信息
      "blind_gift_config_id": 51, // 赠送盲盒时存在数据，疑似是盲盒的配置
      "from": 0, // 不确定用途，观测到 blind_gift_config_id 存在时为0，其余情况无数据
      "gift_action": "爆出", // 赠送盲盒时为爆出，其余无数据
      "gift_tip_price": 16000, // 赠送盲盒时为爆出的礼物价格，其余无数据
      "original_gift_id": 32251, // 赠送盲盒时为盲盒的 gift_id
      "original_gift_name": "心动盲盒", // 赠送盲盒时为盲盒的名称，其余无数据
      "original_gift_price": 15000 // 赠送盲盒时为盲盒的价格，其余无数据
    },
    "broadcast_id": 0, // 广播ID，疑似赠送大礼物触发广播时与其绑定
    "coin_type": "gold", // 硬币类型，目前观测到非付费礼物为silver，付费礼物为gold
    "combo_resources_id": 1, // 待观测，通常是 0 或 1
    "combo_send": {
      // 连击信息
      "action": "投喂", // 行为，一般都是投喂
      "combo_id": "c210a464-9620-425e-b9e3-73db191ed1c5", // 连击ID
      "combo_num": 1, // 当前连击数
      "gift_id": 32128, // 礼物id （盲盒为实际爆出礼物）
      "gift_name": "爱心抱枕", // 礼物名称（盲盒为实际爆出礼物）
      "gift_num": 1, // 数量
      "send_master": null, // 未观测到有效数据
      "uid": 3494362281412802, // 赠送人uid
      "uname": "舒葵交错" // 赠送人名称
    },
    "combo_stay_time": 5, // 连击有效间隔时间
    "combo_total_coin": 16000, // 连击总费用
    "crit_prob": 0, // 待观测，全是0
    "demarcation": 2, // 待观测，数据一般是1，2，3，应该是分类，看起来数字越大越贵
    "discount_price": 16000, // 折扣价格，比如不要钱的粉丝团灯牌
    "dmscore": 952, // 某种评分？待观测
    "draw": 0, // 待观测
    "effect": 0, // 待观测
    "effect_block": 0, // 待观测
    "face": "https://i2.hdslb.com/bfs/face/5d620fea3b4586311884155153a7091b79d0777d.jpg", // 用户头像URL
    "face_effect_id": 0, // 待观测
    "face_effect_type": 0, // 待观测
    "face_effect_v2": {
      // 待观测
      "id": 0, // 待观测
      "type": 0 // 待观测
    },
    "float_sc_resource_id": 0, // 待观测
    "giftId": 32128, // 礼物ID
    "giftName": "爱心抱枕", // 礼物名称
    "giftType": 0, // 礼物类型，枚举，目前发现值 5 疑似免费礼物或背包礼物，其他含义待观测
    "gift_info": {
      // 礼物详细信息
      "effect_id": 0, // 某种ID，目前看好像只有盲盒礼物有，其余为0
      "gif": "https://i0.hdslb.com/bfs/live/ae80d80ea758ff08fb4e2c4226ab7b5011b728a6.gif", // 礼物GIF图
      "has_imaged_gift": 0, // 某种枚举，effect_id非0时为1，其余为0
      "img_basic": "https://s1.hdslb.com/bfs/live/824714c830966d7bec381e35ef808b1f478e21ee.png", // 礼物PNG图
      "webp": "https://i0.hdslb.com/bfs/live/32c8ee42566501822d8ecc68b33cd2c64937266a.webp" // 礼物webp图
    },
    "gift_tag": [
      // 礼物标签？
      1101 // 标签相关，待观测
    ],
    "gold": 0, // 待观测
    "group_medal": null, // 套票相关？不确定，待观测
    "guard_level": 3, // 牌子的大航海类型，0=普通用户，1=总督，2=提督，3=舰长
    "is_first": true, // 待观测，应该是标记本场直播是否是第一次赠送
    "is_join_receiver": false, // 待观测
    "is_naming": false, // 待观测
    "is_special_batch": 0, // 待观测
    "magnification": 1, // 待观测
    "medal_info": {
      // 牌子信息
      "anchor_roomid": 0, // 房间号，目前疑似并未使用
      "anchor_uname": "", // 主播名称，目前疑似并未使用
      "guard_level": 3, // 牌子的大航海类型，0=普通用户，1=总督，2=提督，3=舰长
      "icon_id": 0, // 应该是某ID相关，待观测，目前全是0
      "is_lighted": 1, // 牌子是否点亮 ，1=是，0=否
      "medal_color": 398668, // 牌子颜色（十进制数据，需要自己转十六进制颜色代码）
      "medal_color_border": 6809855, // 牌子边框颜色（十进制数据，需要自己转十六进制颜色代码）
      "medal_color_end": 6850801, // 牌子右侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
      "medal_color_start": 398668, // 牌子左侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
      "medal_level": 25, // 牌子等级
      "medal_name": "娴丢人", // 牌子名称
      "special": "", // 估计是用来区分特殊牌子的，待观测
      "target_id": 3493262186776769 // 牌子所属主播uid
    },
    "name_color": "#00D1F1", // 用户名颜色
    "num": 1, // 赠送数量
    "original_gift_name": "", // 待观测
    "price": 16000, // 礼物价格
    "rcost": 11936982, // 待观测
    "receive_user_info": {
      // 收礼人信息（主播）
      "uid": 3494365156608185, // 主播uid
      "uname": "温以泠" // 主播名称
    },
    "receiver_uinfo": {
      // 收礼人信息（主播）（估计是新版本）
      "base": {
        // 收礼人（主播）基本信息
        "face": "https://i2.hdslb.com/bfs/face/00e03b4b528b6a475d2987f44002c61c4a75d77c.jpg", // 头像
        "is_mystery": false, // 不确定含义，待观测
        "name": "温以泠", // 名称
        "name_color": 0, // 待观测，估计是名字颜色十进制数字
        "name_color_str": "", // 待观测，估计是名字颜色十六进制代码
        "official_info": {
          // 待观测，估计是官方相关
          "desc": "", // ？说明？
          "role": 0, // ？角色？
          "title": "", // ？官方title？
          "type": -1 // ？类型？
        },
        "origin_info": {
          // 待观测，目前看到的都是主播个人信息
          "face": "https://i2.hdslb.com/bfs/face/00e03b4b528b6a475d2987f44002c61c4a75d77c.jpg", // 头像
          "name": "温以泠" // 名称
        },
        "risk_ctrl_info": {
          // 待观测，目前看到的都是主播个人信息
          "face": "https://i2.hdslb.com/bfs/face/00e03b4b528b6a475d2987f44002c61c4a75d77c.jpg", // 头像
          "name": "温以泠" // 名称
        }
      },
      "guard": null, // 待观测，当前未观测到数据
      "guard_leader": null, // 待观测，当前未观测到数据
      "medal": null, // 待观测，当前未观测到数据
      "title": null, // 待观测，当前未观测到数据
      "uhead_frame": null, // 待观测，当前未观测到数据
      "uid": 3494365156608185, // 主播uid
      "wealth": null // 待观测，当前未观测到数据
    },
    "remain": 0, // 待观测
    "rnd": "4568350171557109760", // 待观测
    "send_master": null, // 待观测
    "sender_uinfo": {
      // 送礼人信息
      "base": {
        // 送礼人（用户）基本信息
        "face": "https://i2.hdslb.com/bfs/face/5d620fea3b4586311884155153a7091b79d0777d.jpg", // 头像
        "is_mystery": false, // 不确定含义，待观测
        "name": "舒葵交错", // 名称
        "name_color": 0, // 待观测，估计是名字颜色十进制数字
        "name_color_str": "", // 待观测，估计是名字颜色十六进制代码
        "official_info": {
          // 待观测，估计是官方相关
          "desc": "", // ？说明？
          "role": 0, // ？角色？
          "title": "", // ？官方title？
          "type": -1 // ？类型？
        },
        "origin_info": {
          // 待观测，目前看到的都是送礼人个人信息
          "face": "https://i2.hdslb.com/bfs/face/5d620fea3b4586311884155153a7091b79d0777d.jpg", // 头像
          "name": "舒葵交错" // 名称
        },
        "risk_ctrl_info": {
          // 待观测，目前看到的都是送礼人个人信息
          "face": "https://i2.hdslb.com/bfs/face/5d620fea3b4586311884155153a7091b79d0777d.jpg", // 头像
          "name": "舒葵交错" // 名称
        }
      },
      "guard": null, // 待观测，目前未观察到数据
      "guard_leader": null, // 待观测，目前未观察到数据
      "medal": {
        // 牌子信息
        "color": 398668, // 牌子颜色（十进制数据，需要自己转十六进制颜色代码）
        "color_border": 6809855, // 牌子边框颜色（十进制数据，需要自己转十六进制颜色代码）
        "color_end": 6850801, // 牌子右侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
        "color_start": 398668, // 牌子左侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
        "guard_icon": "https://i0.hdslb.com/bfs/live/143f5ec3003b4080d1b5f817a9efdca46d631945.png", // 大航海图标
        "guard_level": 3, // 大航海类型，0=普通用户，1=总督，2=提督，3=舰长
        "honor_icon": "", // 待观测，目前无数据
        "id": 0, // 待观测，目前都是0
        "is_light": 1, // 牌子是否点亮 ，1=是，0=否
        "level": 27, // 牌子等级
        "name": "泠妻", // 牌子名称
        "ruid": 3494365156608185, // 牌子所属主播uid
        "score": 50093206, // 某种评分？待观测
        "typ": 0, // 待观测，目前都是0
        "user_receive_count": 0, // 待观测，目前都是0
        "v2_medal_color_border": "#58A1F8FF", // v2版本牌子边框颜色
        "v2_medal_color_end": "#4775EFCC", // v2版本牌子右侧颜色（渐变）
        "v2_medal_color_level": "#000B7099", // v2版本牌子等级颜色
        "v2_medal_color_start": "#4775EFCC", // v2版本牌子左侧颜色（渐变）
        "v2_medal_color_text": "#FFFFFFFF" // v2版本牌子内容颜色
      },
      "title": null, // 待观测，目前无数据
      "uhead_frame": null, // 待观测，目前无数据
      "uid": 3494362281412802, // 赠送人uid
      "wealth": null // 待观测，目前都是0
    },
    "silver": 0, // 待观测，目前都是0
    "super": 0, // 待观测，目前都是0
    "super_batch_gift_num": 1, // 待观测，与赠送数量相关
    "super_gift_num": 1, // 待观测，与赠送数量相关
    "svga_block": 0, // 待观测，目前都是0
    "switch": true, // 待观测，目前都是true
    "tag_image": "", // 待观测，目前无数据
    "tid": "4568350171557109760", // 待观测
    "timestamp": 1730123987, // 礼物赠送时间（秒级时间戳）
    "top_list": null, // 待观测，目前无数据
    "total_coin": 15000, // 礼物总价，连击时累加
    "uid": 3494362281412802, // 赠送人uid
    "uname": "舒葵交错", // 赠送人名称
    "wealth_level": 35 // 荣耀等级
  },
  "msg_id": "21794708686651904:1000:1000", // 待观测，感觉跟消息绑定了
  "p_is_ack": true, // 无数据或者TRUE，仍需观测
  "p_msg_type": 1, // 无数据或者1，仍需观测
  "send_time": 1730123987816 // 毫秒级时间戳，有时会没数据，待观测
}

弹幕信息:DANMU_MSG

{
  "cmd": "DANMU_MSG", // 命令
  "dm_v2": "", // 待观察
  "info": [
    // 数据信息
    [
      // 弹幕信息
      0, // 待观测，目前全是0
      4, // 弹幕的 mode 字段
      25, // 弹幕的 fontsize 字段
      14893055, // 弹幕颜色（十进制数据，需要自己转十六进制颜色代码）
      1730214752940, // 发送时的 UNIX 毫秒时间戳
      1730214703, // 待观测
      0, // 待观测，目前全是0
      "d136d2ff", // 一个十六进制数，待观测，可能是颜色
      0, // 待观测，目前全是0
      0, // 待观测，目前全是0
      2, // 待观测，疑似某种类型
      "#19897EFF,#403F388E,#33897EFF", // 待观测，通常为空字符串，info.0.10 == 5 返回一组十六进制颜色代码
      1, // 消息中是否携带表情，1=是，0=否
      {
        // 表情信息，info.0.12 == 1 时为array，其余时候为字符串
        "bulge_display": 1, // 某种枚举，待观测
        "emoticon_unique": "room_30118851_73109", // 表情符号，类似表情ID性质
        "height": 162, // 表情高度
        "in_player_area": 1, // 某种枚举，待观测
        "is_dynamic": 0, // 是否是动态表情，0=否，1=是
        "url": "http://i0.hdslb.com/bfs/live/c45b116a620ba68ce4a6d0ce7bcfc629a4cbbf98.png", // 表情URL图片地址
        "width": 162 // 表情宽度
      },
      "{}", // 字符串表示的 JSON Object,目前未观测到数据
      {
        // 弹幕补充信息，大部分数据都可以在里面获取
        "extra": {
          // 补充信息，json字符串，需要自行转换为对象
          "send_from_me": false, // 是否是自己发送
          "mode": 0, // 弹幕模式 (等同于info[0][1])
          "color": 14893055, // 弹幕颜色 (等同于info[0][3])
          "dm_type": 1, // 某种枚举，待观测
          "font_size": 25, // 	字体大小（等同于info[0][2]）
          "player_mode": 4, // 某种枚举，待观测
          "show_player_type": 0, // 某种枚举，待观测
          "content": "[墨镜]这个表情", // 弹幕文本信息（等同于info[1]）
          "user_hash": "3510031103", // 待观测
          "emoticon_unique": "room_30118851_73109", // 待观测
          "bulge_display": 1, // 待观测
          "recommend_score": 0, // 待观测
          "main_state_dm_color": "", // 待观测
          "objective_state_dm_color": "", // 待观测
          "direction": 0, // 待观测
          "pk_direction": 0, // 待观测
          "quartet_direction": 0, // 待观测
          "anniversary_crowd": 0, // 待观测
          "yeah_space_type": "", // 待观测
          "yeah_space_url": "", // 待观测
          "jump_to_url": "", // 待观测
          "space_type": "", // 待观测
          "space_url": "", // 待观测
          "animation": {}, // 待观测，目前未观测到数据
          "emots": {
            // 文本中使用过的表情信息，对象类型，key为表情，例如：[墨镜]
            "[墨镜]": {
              // 某个表情，key为对应的文本
              "count": 1, // 文本中出现的数量
              "descript": "[墨镜]", // 描述
              "emoji": "[墨镜]", // 描述
              "emoticon_id": 273, // 待观测
              "emoticon_unique": "emoji_273", // 待观测
              "height": 20, // 图片高度
              "url": "http://i0.hdslb.com/bfs/live/5e01c237642c8b662a69e21b8e0fbe6e7dbc2aa1.png", // 图片url
              "width": 20 // 图片宽度
            }
          },
          "is_audited": false, // 待观测
          "id_str": "0b0b20c622a374dc3e1e327bb76720fb63", // 待观测
          "icon": null, // 待观测
          "show_reply": true, // 是否允许回复
          "reply_mid": 0, // 回复消息发送人uid
          "reply_uname": "", // 回复消息发送人名称
          "reply_uname_color": "", // 回复消息发送人名字颜色
          "reply_is_mystery": false, // 待观测
          "reply_type_enum": 0, // 待观测，某种枚举
          "hit_combo": 0, // 待观测，疑似是一些重内容连续发送的连击数
          "esports_jump_url": "" // 待观测
        },
        "mode": 0, // 某种枚举，待观测
        "show_player_type": 0, // 某种枚举，待观测
        "user": {
          // 弹幕发送人信息
          "base": {
            // 发送人基本信息
            "face": "https://i1.hdslb.com/bfs/face/1bddafc0564fd84e6da7f262c6c37deb6605d623.jpg", // 头像
            "is_mystery": false, // 不确定含义，待观测
            "name": "岚烟y", // 名称
            "name_color": 0, // 待观测，估计是名字颜色十进制数字
            "name_color_str": "", // 待观测，估计是名字颜色十六进制代码
            "official_info": {
              // 待观测，估计是官方相关
              "desc": "", // ？说明？
              "role": 0, // ？角色？
              "title": "", // ？官方title？
              "type": -1 // ？类型
            },
            "origin_info": {
              // 待观测，目前看到的都是发送人个人信息
              "face": "https://i1.hdslb.com/bfs/face/1bddafc0564fd84e6da7f262c6c37deb6605d623.jpg", // 头像
              "name": "岚烟y" // 名称
            },
            "risk_ctrl_info": {
              // 待观测，目前看到的都是发送人个人信息
              "face": "https://i1.hdslb.com/bfs/face/1bddafc0564fd84e6da7f262c6c37deb6605d623.jpg", // 头像
              "name": "岚烟y" // 名称
            }
          },
          "guard": null, // 待观测，怀疑可能跟超管有关
          "guard_leader": {
            // 待观测，怀疑可能跟超管有关
            "is_guard_leader": false // 待观测，怀疑可能跟超管有关
          },
          "medal": {
            // 牌子信息
            "color": 398668, // 牌子颜色（十进制数据，需要自己转十六进制颜色代码）
            "color_border": 16771156, // 牌子边框颜色（十进制数据，需要自己转十六进制颜色代码）
            "color_end": 6850801, // 牌子右侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
            "color_start": 398668, // 牌子左侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
            "guard_icon": "https://i0.hdslb.com/bfs/live/98a201c14a64e860a758f089144dcf3f42e7038c.png", // 大航海图标
            "guard_level": 2, // 大航海类型，0=普通用户，1=总督，2=提督，3=舰长
            "honor_icon": "", // 待观测，目前无数据
            "id": 1130856, // 待观测，目前都是0
            "is_light": 1, // 牌子是否点亮 ，1=是，0=否
            "level": 26, // 牌子等级
            "name": "泠妻", // 牌子名称
            "ruid": 3494365156608185, // 牌子所属主播uid
            "score": 50046632, // 某种评分？待观测
            "typ": 0, // 待观测，目前都是0
            "user_receive_count": 0, // 待观测，目前都是0
            "v2_medal_color_border": "#58A1F8FF", // v2版本牌子边框颜色
            "v2_medal_color_end": "#4775EFCC", // v2版本牌子右侧颜色（渐变）
            "v2_medal_color_level": "#000B7099", // v2版本牌子等级颜色
            "v2_medal_color_start": "#4775EFCC", // v2版本牌子左侧颜色（渐变）
            "v2_medal_color_text": "#FFFFFFFF" // v2版本牌子内容颜色
          },
          "title": {
            // 待观测
            "old_title_css_id": "", // 待观测
            "title_css_id": "" // 待观测
          },
          "uhead_frame": null, // 待观测，目前无数据
          "uid": 400970605, // uid
          "wealth": null // 待观测
        }
      },
      {
        // 疑似活动信息，待观测
        "activity_identity": "", // 待观测
        "activity_source": 0, // 待观测
        "not_show": 0 // 待观测
      },
      42 // 待观测
    ],
    "[墨镜]这个表情", // 弹幕信息
    [
      // 用户信息
      400970605, // 用户uid
      "岚烟y", // 用户名称
      1, // 待观测
      0, // 待观测
      0, // 待观测
      10000, // 待观测
      1, // 待观测
      "#E17AFF" // 待观测，某种颜色信息，有时为空
    ],
    [
      // 牌子信息
      26, // 牌子等级
      "泠妻", // 牌子名称
      "温以泠", // 牌子所属主播名称
      30118851, // 牌子所属直播间房间号
      398668, // 牌子颜色（十进制数据，需要自己转十六进制颜色代码）
      "", // 待观测，一直是空
      0, // 待观测，一直是0
      16771156, // 牌子边框颜色（十进制数据，需要自己转十六进制颜色代码）
      398668, // 牌子左侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
      6850801, // 牌子右侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
      2, // 大航海类型，0=普通用户，1=总督，2=提督，3=舰长
      1, // 牌子是否点亮 ，1=是，0=否
      3494365156608185 // 牌子所属主播uid
    ],
    [
      // 疑似什么等级信息
      15, // 疑似什么等级
      0, // 待观测，目前都是0
      6406234, // 颜色（十进制数据，需要自己转十六进制颜色代码）
      ">50000", // 待观测，疑似当前什么等级经验值
      0 // 待观测，某种枚举
    ],
    [
      // 待观测
      "", // 待观测，大部分为空串，少部分存在数据，不确定用途
      "" // 待观测，大部分为空串，少部分存在数据，不确定用途
    ],
    0, // 待观测，一直都是0
    2, // 疑似大航海类型
    null, // 待观测，一直都是空
    {
      // 发送时间戳
      "ct": "F2A502B4", // 待观测，某十六进制数据
      "ts": 1730214752 // 秒级时间戳，应该是发送时间
    },
    0, // 待观测，一直都是0
    0, // 待观测，一直都是0
    null, // 待观测，一直都是空
    null, // 待观测，一直都是空
    0, // 待观测，一直都是0
    594, // 待观测
    [
      // 待观测，疑似某种等级信息
      28 // 待观测，疑似某种等级信息
    ],
    null // 待观测
  ]
}

开通大航海:GUARD_BUY

{
  "cmd": "GUARD_BUY", // 固定命令
  "data": {
    // 数据信息
    "uid": 24967532, // 用户uid
    "username": "骸骸家的三哥哥", // 用户名
    "guard_level": 3, // 开通类型，1=总督，2=提督，3=舰长
    "num": 1, // 开通数量
    "price": 198000, // 价值（电池*100）
    "gift_id": 10003, // 礼物ID
    "gift_name": "舰长", // 礼物名称
    "start_time": 1730438935, // 上舰时间
    "end_time": 1730438935 // 上舰时间
  }
}

千舰推送:GUARD_LOTTERY_START

{
  "cmd": "GUARD_HONOR_THOUSAND", // 固定命令
  "data": {
    // 数据信息
    "add": [
      // 新增千舰
      13164144, // 主播的uid
      433351 // 主播的uid
    ],
    "del": [
      // 退出千舰
      3537115310721781, // 主播的uid
      3493273152784750 // 主播的uid
    ]
  }
}

上舰抽奖消息推送:USER_TOAST_MSG

| 字段 | 字段类型 | 字段说明 | | :------------------------ | :------- | :------------------------------------------------- | | cmd | string | 固定命令 | | data | array | 数据信息 | | data.anchor_show | bool | 待观测，疑似是否在直播间展示，通常为 true | | data.color | string | 某种颜色值 | | data.dmscore | int | 待观测 | | data.effect_id | int | 待观测 | | data.end_time | int | 结束时间（秒级时间戳），与开始时间相同 | | data.face_effect_id | int | 待观测 | | data.gift_id | int | 礼物 ID | | data.group_name | int | 待观测 | | data.group_op_type | int | 待观测 | | data.group_role_name | int | 待观测 | | data.guard_level | int | 开通大航海类型，0=普通用户，1=总督，2=提督，3=舰长 | | data.is_group | int | 待观测 | | data.is_show | int | 待观测 | | data.num | int | 开通数量 | | data.op_type | int | 待观测 | | data.payflow_id | string | 待观测 | | data.price | int | 大航海价格（电池*100） | | data.role_name | string | 身份名称 | | data.room_effect_id | int | 待观测 | | data.room_gift_effect_id | int | 待观测 | | data.room_group_effect_id | int | 待观测 | | data.source | int | 待观测 | | data.start_time | int | 开始时间（秒级时间戳），与开始时间相同 | | data.svga_block | int | 待观测 | | data.target_guard_count | int | 待观测 | | data.toast_msg | string | 在直播间中发送的文字内容 | | data.uid | int | 开通用户 uid | | data.unit | string | 开通单位 | | data.user_show | bool | 跟显示相关？待观测 | | data.username | string | 开通用户名称 |

{
  "cmd": "USER_TOAST_MSG", // 固定命令
  "data": {
    // 数据信息
    "anchor_show": true, // 待观测，疑似是否在直播间展示，通常为true
    "color": "#00D1F1", // 某种颜色值
    "dmscore": 306, // 待观测
    "effect_id": 397, // 待观测
    "end_time": 1730361519, // 结束时间（秒级时间戳），与开始时间相同
    "face_effect_id": 44, // 待观测
    "gift_id": 10003, // 礼物ID
    "group_name": "", // 待观测
    "group_op_type": 0, // 待观测
    "group_role_name": "", // 待观测
    "guard_level": 3, // 开通大航海类型，0=普通用户，1=总督，2=提督，3=舰长
    "is_group": 0, // 待观测
    "is_show": 0, // 待观测
    "num": 1, // 开通数量
    "op_type": 2, // 待观测
    "payflow_id": "2410311558284912114936330", // 待观测
    "price": 168000, // 大航海价格（电池*100）
    "role_name": "舰长", // 身份名称
    "room_effect_id": 590, // 待观测
    "room_gift_effect_id": 0, // 待观测
    "room_group_effect_id": 1337, // 待观测
    "source": 0, // 待观测
    "start_time": 1730361519, // 开始时间（秒级时间戳），与开始时间相同
    "svga_block": 0, // 待观测
    "target_guard_count": 64, // 待观测
    "toast_msg": "<%尘世七仙%> 在主播温以泠的直播间续费了舰长，今天是TA陪伴主播的第325天", // 在直播间中发送的文字内容
    "uid": 1517971493, // 开通用户uid
    "unit": "月", // 开通单位
    "user_show": true, // 跟显示相关？待观测
    "username": "尘世七仙" // 开通用户名称
  },
  "msg_id": "21919243995990016:1000:1000",
  "p_is_ack": true,
  "p_msg_type": 1,
  "send_time": 1730361520068
}

醒目留言:SUPER_CHAT_MESSAGE

{
  "cmd": "SUPER_CHAT_MESSAGE", // 固定命令
  "data": {
    // 数据信息
    "background_bottom_color": "#2A60B2", // 底部正文区域背景色
    "background_color": "#EDF5FF", // 底部正文文字颜色
    "background_color_end": "#405D85", // 牌子右侧颜色（渐变）
    "background_color_start": "#3171D2", // 牌子左侧颜色（渐变）
    "background_icon": "", // ？背景图标？
    "background_image": "", // ？背景图片？
    "background_price_color": "#7497CD", // ？价格背景颜色？
    "color_point": 0.7, // 待观测
    "dmscore": 952, // 待观测
    "end_time": 1730468880, // 醒目留言结束时间（秒级时间戳）
    "gift": {
      // 礼物信息
      "gift_id": 12000, // 礼物ID
      "gift_name": "醒目留言", // 礼物名称
      "num": 1 // 赠送数量
    },
    "group_medal": {
      // 待观测，疑似套票
      "is_lighted": 0, // 疑似套票是否点亮，1=是，0=否
      "medal_id": 0, // 疑似套票id
      "name": "" // 疑似套票名称
    },
    "id": 10857495, // 疑似醒目留言ID
    "is_mystery": false, // 待观测
    "is_ranked": 0, // 待观测
    "is_send_audit": 0, // 待观测
    "medal_info": {
      // 牌子信息
      "anchor_roomid": 22384516, // 房间号
      "anchor_uname": "呜米", // 主播名称
      "guard_level": 3, // 牌子的大航海类型，0=普通用户，1=总督，2=提督，3=舰长
      "icon_id": 0, // 应该是某ID相关，待观测，目前全是0
      "is_lighted": 1, // 牌子是否点亮 ，1=是，0=否
      "medal_color": "#2d0855", // 牌子颜色（十六进制颜色代码）
      "medal_color_border": 6809855, // 牌子边框颜色（十进制数据，需要自己转十六进制颜色代码）
      "medal_color_end": 10329087, // 牌子右侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
      "medal_color_start": 2951253, // 牌子左侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
      "medal_level": 29, // 牌子等级
      "medal_name": "小米星", // 牌子名称
      "special": "", // 估计是用来区分特殊牌子的，待观测
      "target_id": 617459493 // 牌子所属主播uid
    },
    "message": "说实话2.0这个皮套当时吸引我留下来的很大原因（小声）后面成功转型为歌粉", // 醒目留言内容
    "message_font_color": "#A3F6FF", // 醒目留言颜色
    "message_trans": "", // 日语信息
    "price": 30, // 单价？电池/10
    "rate": 1000, // 待观测，会不会是用来计算价格的？比如 price * rate = 电池*100
    "start_time": 1730468820, // 醒目留言开始时间（秒级时间戳）
    "time": 60, // 醒目留言持续时间
    "token": "5D8E7A9D", // 待观测
    "trans_mark": 0, // 待观测
    "ts": 1730468820, // 醒目留言开始时间（秒级时间戳）
    "uid": 15589465, // 发送用户uid
    "uinfo": {
      // 发送用户信息
      "base": {
        // 基本信息
        "face": "https://i1.hdslb.com/bfs/face/fad0fa8d7cb85f82fde486fc49b8766e00d7272b.jpg", // 头像URL
        "is_mystery": false, // 不确定含义，待观测
        "name": "唯心的狐狸", // 名称
        "name_color": 0, // 待观测，估计是名字颜色十进制数字
        "name_color_str": "#00D1F1", // 待观测，估计是名字颜色十六进制代码
        "official_info": {
          // 待观测，估计是官方相关
          "desc": "", // ？说明？
          "role": 0, // ？角色？
          "title": "", // ？官方title？
          "type": -1 // ？类型？
        },
        "origin_info": {
          // 待观测，目前看到的都是用户个人信息
          "face": "https://i1.hdslb.com/bfs/face/fad0fa8d7cb85f82fde486fc49b8766e00d7272b.jpg", // 头像URL
          "name": "唯心的狐狸" // 名称
        },
        "risk_ctrl_info": {
          // 待观测，目前看到的都是用户个人信息
          "face": "https://i1.hdslb.com/bfs/face/fad0fa8d7cb85f82fde486fc49b8766e00d7272b.jpg", // 头像URL
          "name": "唯心的狐狸" // 名称
        }
      },
      "guard": {
        // 大航海应该是，如果不是大航海就是null
        "expired_str": "2025-11-14 23:59:59", // 到期时间
        "level": 3 // 大航海类型，0=普通用户，1=总督，2=提督，3=舰长
      },
      "guard_leader": null, // 房管的领导？
      "medal": {
        // 牌子信息
        "color": 2951253, // 牌子颜色（十进制数据，需要自己转十六进制颜色代码）
        "color_border": 6809855, // 牌子边框颜色（十进制数据，需要自己转十六进制颜色代码）
        "color_end": 10329087, // 牌子右侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
        "color_start": 2951253, // 牌子左侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
        "guard_icon": "https://i0.hdslb.com/bfs/live/143f5ec3003b4080d1b5f817a9efdca46d631945.png", // 大航海图标URL
        "guard_level": 3, // 大航海类型，0=普通用户，1=总督，2=提督，3=舰长
        "honor_icon": "", // 待观测，目前无数据
        "id": 0, // 待观测，目前都是0
        "is_light": 1, // 牌子是否点亮 ，1=是，0=否
        "level": 29, // 牌子等级
        "name": "小米星", // 牌子名称
        "ruid": 617459493, // 牌子所属主播uid
        "score": 50505386, // 某种评分？待观测
        "typ": 0, // 待观测，目前都是0
        "user_receive_count": 0, // 待观测，目前都是0
        "v2_medal_color_border": "#D47AFFFF", // v2版本牌子边框颜色
        "v2_medal_color_end": "#9660E5CC", // v2版本牌子右侧颜色（渐变）
        "v2_medal_color_level": "#6C00A099", // v2版本牌子等级颜色
        "v2_medal_color_start": "#9660E5CC", // v2版本牌子左侧颜色（渐变）
        "v2_medal_color_text": "#FFFFFFFF" // v2版本牌子内容颜色
      },
      "title": {
        // 待观测，当前未观测到数据
        "old_title_css_id": "", // 待观测，当前未观测到数据
        "title_css_id": "" // 待观测，当前未观测到数据
      },
      "uhead_frame": null, // 待观测，当前未观测到数据
      "uid": 15589465, // 用户uid
      "wealth": null // 待观测，当前未观测到数据
    },
    "user_info": {
      // 也是用户信息
      "face": "https://i1.hdslb.com/bfs/face/fad0fa8d7cb85f82fde486fc49b8766e00d7272b.jpg", // 用户头像
      "face_frame": "https://i0.hdslb.com/bfs/live/80f732943cc3367029df65e267960d56736a82ee.png", // 用户头像框
      "guard_level": 3, // 大航海类型，0=普通用户，1=总督，2=提督，3=舰长
      "is_main_vip": 1, // 待观测，看起来是是否是某种，1=是，0=否
      "is_svip": 0, // 待观测，看起来是是否是某种，1=是，0=否
      "is_vip": 0, // 待观测，看起来是是否是某种，1=是，0=否
      "level_color": "#5896de", // 用户等级颜色
      "manager": 0, // 待观测
      "name_color": "#00D1F1", // 用户名字颜色
      "title": "", // 待观测，当前未观测到数据
      "uname": "唯心的狐狸", // 用户名
      "user_level": 24 // 用户等级
    }
  },
  "is_report": true,
  "msg_id": "21975500356352512:1000:1000",
  "p_is_ack": true,
  "p_msg_type": 1,
  "send_time": 1730468820560
}

舰长进入直播间:ENTRY_EFFECT

{
  "cmd": "ENTRY_EFFECT",
  "data": {
    "id": 381, // id
    "uid": 28726406, // 用户uid
    "target_id": 617459493, // 主播uid
    "mock_effect": 0, // 待观测
    "face": "https://i2.hdslb.com/bfs/face/cbbe6b3ebf859640afd9fd67897ea6089dea8b51.webp", // 用户头像
    "privilege_type": 3, // 特权类型，0=普通用户，1=总督，2=提督，3=舰长
    "copy_writing": "<%ユリが一番好き%> 来了", // 网页中出现的欢迎文案
    "copy_color": "#F7F7F7", // 文字颜色
    "highlight_color": "#FFFFFF", // 文字突出颜色
    "priority": 1, // 优先级，应该是数字越大越靠前
    "basemap_url": "https://i0.hdslb.com/bfs/live/mlive/aee950e6aacddd0b125506f0a47d7fc1695d3ece.png", // 欢迎进入时的背景图
    "show_avatar": 0, // 是否显示头像，0=否，1=是
    "effective_time": 4, // 有效时间，单位应该是秒
    "web_basemap_url": "https://i0.hdslb.com/bfs/live/mlive/aee950e6aacddd0b125506f0a47d7fc1695d3ece.png", // web版欢迎进入时的背景图
    "web_effective_time": 4, // web版有效时间，单位应该是秒
    "web_effect_close": 1, // 待观测
    "web_close_time": 900, // 待观测
    "business": 6, // 待观测，像是区分了欢迎背景图的类型
    "copy_writing_v2": "<%ユリが一番好…%> 来了", // 网页中出现的欢迎文案
    "icon_list": [
      // 待观测
    ],
    "max_delay_time": 7, // 疑似最长停留时间？
    "trigger_time": 1730559246176328524, // 待观测
    "identities": 1, // 待观测
    "effect_silent_time": 0, // 待观测
    "effective_time_new": 0, // 待观测
    "web_dynamic_url_webp": "", // 待观测
    "web_dynamic_url_apng": "", // 待观测
    "mobile_dynamic_url_webp": "", // 待观测
    "wealthy_info": {
      // 荣耀等级信息
      "uid": 0, // 待观测
      "level": 28, // 荣耀等级
      "level_total_score": 0, // 待观测
      "cur_score": 0, // 待观测
      "upgrade_need_score": 0, // 待观测
      "status": 0, // 待观测
      "dm_icon_key": "" // 待观测
    },
    "new_style": 1, // 待观测
    "is_mystery": false, // 待观测
    "uinfo": {
      // 用户信息
      "uid": 28726406, // 用户uid
      "base": {
        // 基本信息
        "name": "ユリが一番好き", // 名称
        "face": "https://i2.hdslb.com/bfs/face/cbbe6b3ebf859640afd9fd67897ea6089dea8b51.webp", // 头像
        "name_color": 0, // 待观测
        "is_mystery": false, // 待观测
        "risk_ctrl_info": null, // 待观测
        "origin_info": null, // 待观测
        "official_info": null, // 待观测
        "name_color_str": "#00D1F1" // 名字颜色？
      },
      "medal": {
        // 牌子信息
        "name": "小米星", // 牌子名称
        "level": 25, // 牌子等级
        "color_start": 398668, // 牌子左侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
        "color_end": 6850801, // 牌子右侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
        "color_border": 6809855, // 牌子边框颜色（十进制数据，需要自己转十六进制颜色代码）
        "color": 398668, // 牌子颜色（十进制数据，需要自己转十六进制颜色代码）
        "id": 310969, // 待观测
        "typ": 0, // 待观测，目前都是0
        "is_light": 1, // 牌子是否点亮 ，1=是，0=否
        "ruid": 617459493, // 主播uid
        "guard_level": 3, // 大航海类型，0=普通用户，1=总督，2=提督，3=舰长
        "score": 50027800, // 某种评分？待观测
        "guard_icon": "https://i0.hdslb.com/bfs/live/143f5ec3003b4080d1b5f817a9efdca46d631945.png", // 大航海图标URL
        "honor_icon": "", // 待观测，目前无数据
        "v2_medal_color_start": "#4775EFCC", // v2版本牌子左侧颜色（渐变）
        "v2_medal_color_end": "#4775EFCC", // v2版本牌子右侧颜色（渐变）
        "v2_medal_color_border": "#58A1F8FF", // v2版本牌子边框颜色
        "v2_medal_color_text": "#FFFFFFFF", // v2版本牌子内容颜色
        "v2_medal_color_level": "#000B7099", // v2版本牌子等级颜色
        "user_receive_count": 0 // 待观测，目前都是0
      },
      "wealth": {
        // 荣耀等级
        "level": 28, // 荣耀等级
        "dm_icon_key": "" // 待观测
      },
      "title": null, // 待观测
      "guard": {
        // 大航海信息
        "level": 3, // 大航海类型，0=普通用户，1=总督，2=提督，3=舰长
        "expired_str": "2024-11-17 23:59:59" // 到期日期
      },
      "uhead_frame": null, // 待观测
      "guard_leader": null // 待观测
    },
    "full_cartoon_id": 0, // 待观测
    "priority_level": 0, // 待观测
    "wealth_style_info": {
      // 荣耀等级图片
      "url": "https://i0.hdslb.com/bfs/live/62fe89aef112353cfd97016b4b2cc653438642ac.png" // 荣耀等级图片URL
    }
  }
}

直播间互动:INTERACT_WORD

{
  "cmd": "INTERACT_WORD", // 固定命令
  "data": {
    // 数据信息
    "contribution": {
      // ？贡献？
      "grade": 0 // 待观测，看起来都是0
    },
    "contribution_v2": {
      // ？贡献V2版本？
      "grade": 0, // 待观测，看起来都是0
      "rank_type": "", // 待观测，看起来都是空字符串
      "text": "" // 待观测，看起来都是空字符串
    },
    "core_user_type": 3, // 某种用户类型，等待观测
    "dmscore": 22, // 待观测
    "fans_medal": {
      // 牌子信息
      "anchor_roomid": 22384516, // 牌子主播房间号
      "guard_level": 0, // 大航海类型
      "icon_id": 0, // 待观测，某种ID
      "is_lighted": 0, // 是否点亮，1=是，0=否
      "medal_color": 398668, // 牌子颜色（十进制数据，需要自己转十六进制颜色代码）
      "medal_color_border": 6809855, // 牌子边框颜色（十进制数据，需要自己转十六进制颜色代码）
      "medal_color_end": 6850801, // 牌子右侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
      "medal_color_start": 398668, // 牌子左侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
      "medal_level": 10, // 牌子等级
      "medal_name": "小米星", // 牌子名称
      "score": 13082, // 待观测，某种分数
      "special": "", // 待观测
      "target_id": 617459493 // 牌子主播id
    },
    "group_medal": {
      // 套票信息
      "is_lighted": 1, // 是否点亮
      "medal_id": 9, // 套票id
      "name": "MeUmy" // 套票名称
    },
    "identities": [
      // 待观测，？某种身份？
      1
    ],
    "is_mystery": false, // 待观测，疑似是否是未登陆用户
    "is_spread": 1, // 是否是推广用户，1=是，0=否
    "msg_type": 1, // 消息类型，1=进入直播间，2=关注，3=分享直播间
    "privilege_type": 0, // 大航海类型，0=普通用户，1=总督，2=提督，3=舰长
    "relation_tail": {
      // 尾部说明
      "tail_guide_text": "曾经活跃过，近期与你互动较少", // 指导文本
      "tail_icon": "https://i0.hdslb.com/bfs/live/bb88734558c6383a4cfb5fa16c9749d5290d95e8.png", // 指导图标
      "tail_type": 4 // 内容类型
    },
    "roomid": 22384516, // 直播间房间号
    "score": 1730642535456, // 待观测
    "spread_desc": "流量包推广", // 推广来源
    "spread_info": "#FF649E", // 展示推广来源文字颜色
    "tail_icon": 0, // 待观测
    "tail_text": "", // 待观测
    "timestamp": 1730642525, // 互动时间（秒级时间戳）
    "trigger_time": 1730642525444320300, // 待观测
    "uid": 439150369, // 用户uid
    "uinfo": {
      // 用户信息
      "base": {
        // 基本信息
        "face": "https://i1.hdslb.com/bfs/face/6c3ff0055a77286e2d0cdf7a27413fb207906c26.jpg", // 用户头像
        "is_mystery": false, // 待观测，疑似是否是未登陆用户
        "name": "大大怪----------", // 名称
        "name_color": 0, // 名字颜色十进制数字
        "name_color_str": "", //名字颜色十六进制代码
        "official_info": {
          // 待观测，估计是官方相关
          "desc": "", // ？说明？
          "role": 0, // ？角色？
          "title": "", // ？官方title？
          "type": -1 // ？类型？
        },
        "origin_info": {
          // 待观测，目前看到的都是用户个人信息
          "face": "https://i1.hdslb.com/bfs/face/6c3ff0055a77286e2d0cdf7a27413fb207906c26.jpg", // 头像
          "name": "大大怪----------" // 名称
        },
        "risk_ctrl_info": {
          // 待观测，目前看到的都是用户个人信息
          "face": "https://i1.hdslb.com/bfs/face/6c3ff0055a77286e2d0cdf7a27413fb207906c26.jpg", // 头像
          "name": "大大怪----------" // 名称
        }
      },
      "guard": {
        // 大航海信息
        "level": 3, // 大航海类型，0=普通用户，1=总督，2=提督，3=舰长
        "expired_str": "2024-11-17 23:59:59" // 到期日期
      },
      "guard_leader": null, // 待观测
      "medal": {
        // 牌子信息
        "color": 398668, // 牌子颜色（十进制数据，需要自己转十六进制颜色代码）
        "color_border": 6809855, // 牌子边框颜色（十进制数据，需要自己转十六进制颜色代码）
        "color_end": 6850801, // 牌子右侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
        "color_start": 398668, // 牌子左侧颜色（渐变）（十进制数据，需要自己转十六进制颜色代码）
        "guard_icon": "https://i0.hdslb.com/bfs/live/143f5ec3003b4080d1b5f817a9efdca46d631945.png", // 大航海图标
        "guard_level": 3, // 大航海类型，0=普通用户，1=总督，2=提督，3=舰长
        "honor_icon": "", // 待观测，目前无数据
        "id": 0, // 待观测，目前都是0
        "is_light": 1, // 牌子是否点亮，1=是，0=否
        "level": 27, // 牌子等级
        "name": "泠妻", // 牌子名称
        "ruid": 3494365156608185, // 牌子所属主播uid
        "score": 50093206, // 某种评分？待观测
        "typ": 0, // 待观测，目前都是0
        "user_receive_count": 0, // 待观测，目前都是0
        "v2_medal_color_border": "#58A1F8FF", // v2版本牌子边框颜色
        "v2_medal_color_end": "#4775EFCC", // v2版本牌子右侧颜色（渐变）
        "v2_medal_color_level": "#000B7099", // v2版本牌子等级颜色
        "v2_medal_color_start": "#4775EFCC", // v2版本牌子左侧颜色（渐变）
        "v2_medal_color_text": "#FFFFFFFF" // v2版本牌子内容颜色
      },
      "title": null, // 待观测
      "uhead_frame": {
        // 头像框信息
        "frame_img": "https://i0.hdslb.com/bfs/live/80f732943cc3367029df65e267960d56736a82ee.png", // 头像框URL
        "id": 1775 // 头像框ID
      },
      "uid": 481471034, // 用户uid
      "wealth": {
        // 待观测
        "dm_icon_key": "", // 待观测
        "level": 24 // 待观测
      }
    },
    "uname": "欧豆豆的派大星", // 用户名
    "uname_color": "" // 用户名颜色
  }
}

PK 即将开始:PK_BATTLE_PRE_NEW

{
  "cmd": "PK_BATTLE_PRE_NEW", // 固定命令
  "pk_id": 360499657, // PKID
  "pk_status": 101, // pk状态，代表值待观察
  "status_msg": "", // pk状态文字说明
  "timestamp": 1730295557, // 时间
  "data": {
    // 数据信息
    "is_followed": 0, // 待观测
    "uname": "西红柿教主大人", // pk对象的名称
    "face": "https://i2.hdslb.com/bfs/face/638b5ce6a4ecc689ea76a94ba7119fa8ffb53b41.jpg", // pk对象的头像
    "uid": 471024854, // pk对象的uid
    "room_id": 31948297, // pk对象的房间号
    "season_id": 78, // 待观测
    "pre_timer": 10, // 前置定时器（10秒后开始pk）
    "pk_votes_name": "PK值", // pk得分名称
    "end_win_task": null, // 待观测
    "battle_type": 2, // pk类型
    "match_type": 1, // 待观测
    "battle_sub_type": 7 // 待观测
  },
  "template_id": "multi_conn_grid" // 待观测
}

有用的命令

几个比较实用的状态，持续更新中...

赠送礼物

盲盒亏损

通过判断 data.blind_gift 的数据来取得，当 data.blind_gift 存在数据时，则可判断礼物是盲盒礼物

data.blind_gift.original_gift_price：盲盒的价格（电池*100）
data.blind_gift.gift_tip_price：爆出礼物的价格（电池*100）
data.blind_gift.original_gift_id：盲盒的 ID
data.blind_gift.original_gift_name：盲盒的名称

通过盲盒 ID 或名称分类可以记录没种盲盒的盈亏

更进一步通过 data.uid 字段分类可记录每个用户&每种盲盒的盈亏

感谢礼物

接收到数据即为有人赠送了礼物

如果有需要，可以通过判断 data.coin_type == gold 或者 data.giftType != 5 来过滤免费礼物

礼物总价可以通过 data.price * data.num 获得

B 站发言有频率限制，建议发送消息的逻辑单做一条队列，每 3 秒执行一条发送

进阶：建议将 感谢礼物事件 封装成队列，每当有需要感谢的礼物出现时加入队列，同一个用户赠送数据合并，当 消息发送队列 无更高优先级任务时取一条进行感谢，可以避免同一用户短时间大量赠送带来的问题

data.uid：送礼人 uid
data.uname：送礼人名称
data.coin_type：礼物是否是免费礼物
data.giftId：礼物 ID
data.giftName：礼物名称
data.price：礼物单价
data.num：赠送数量
receiver_uinfo.uid：收礼人 uid（主播的 id）
sender_uinfo.medal.ruid：用户携带的牌子归属主播的 uid（可以根据 receiver_uinfo.uid == sender_uinfo.medal.ruid 来确认送礼人携带的当前主播的牌子）
sender_uinfo.medal.guard_level：大航海类型，0=普通用户，1=总督，2=提督，3=舰长（所携带的牌子，有可能不是主播的，需要自行判断）
sender_uinfo.medal.level：牌子等级（所携带的牌子，有可能不是主播的，需要自行判断）

理论上可以连击信息来判断在连击结束之后所有的礼物一起感谢，但因工作比较忙还没有时间去观测对应的数据，后续补全

弹幕信息

自动回复

通过检查弹幕信息，可以为关键词匹配自动回复

建议留足配置空间，以便拓展，例如：

多关键词配置，命中一个就触发或全部命中才触发

黑名单配置，某些用户的发言不触发自动回复

多禁词配置，与关键词相同，命中一个就不触发自动回复或全部命中就不触发自动回复

多回复项，可以配置多个回复项在触发自动回复时随机触发一条

info.1：文本信息
info.2.0：发送人 uid
info.2.1：发送人用户名
info.3.3：牌子所属房间号（可以通过该字段与链接的房间号匹配判断携带的当前主播的牌子）
info.3.10：大航海类型，0=普通用户，1=总督，2=提督，3=舰长（所携带的牌子，有可能不是主播的，需要自行判断）
info.3.0：牌子等级（所携带的牌子，有可能不是主播的，需要自行判断）

弹幕信息事件可以做的事情非常多，类似抽奖一类的与弹幕互动的功能均可实现，拓展性极强

开通舰长

感谢上舰

当前开通大航海已经不会触发 SEND_GIFT 事件，需要单独处理

舰长进入直播间

进房欢迎

对来到直播间的用户进行欢迎

建议在进房量少时再启用，或根据牌子进行过滤，否则大量进房信息积压会导致机器人欢迎不及时

data.uinfo.medal.ruid：用户携带的牌子归属主播的 uid（目前看来可以根据 data.target_id == data.uinfo.medal.ruid 来判断用户携带的是否是主播自己的牌子）
data.uinfo.medal.guard_level：大航海类型，0=普通用户，1=总督，2=提督，3=舰长（所携带的牌子，有可能不是主播的，需要自行判断）
data.uinfo.medal.level：牌子等级（所携带的牌子，有可能不是主播的，需要自行判断）
data.uinfo.base.name：用户名
data.uinfo.uid：用户 ID

直播间互动

进房欢迎 & 感谢关注 & 感谢分享

三个消息都由一个推送进行，通过 data.msg_type 进行区分

建议在进房量少时再启用，或根据牌子进行过滤，否则大量进房信息积压会导致机器人欢迎不及时

data.fans_medal.anchor_roomid：牌子主播房间号（目前看来可以根据 data.fans_medal.anchor_roomid == 直播间房间号 来判断用户携带的是否是主播自己的牌子）
data.fans_medal.guard_level：大航海类型，0=普通用户，1=总督，2=提督，3=舰长（所携带的牌子，有可能不是主播的，需要自行判断）
data.uid：用户 uid
data.uname：用户名称
data.msg_type：消息类型，1=进入直播间，2=关注，3=分享直播间

PK 即将开始

PK 播报

可以在 PK 开始之前（前 10 秒）获取到 PK 方的信息，通过该信息可查询对方直播间的信息并进行播报

data.uid：主播 uid
data.uname：主播名称
data.room_id：直播间房间号

从PHP-FPM到常驻进程：Swoole与Workerman的优劣与对比

Wed, 23 Oct 2024 10:59:36 GMT

在 PHP 开发中，传统的 PHP-FPM 模式一直是主流，但随着高并发和实时通信场景的增多，常驻进程模式的框架如 Swoole 和 Workerman 逐渐受到了关注。这些框架通过异步非阻塞 IO 和常驻进程模型，能够显著提升应用的并发处理能力。那么，这些框架与传统的 PHP-FPM 模式相比，有哪些优劣？本文将从架构特点、性能表现和使用场景等方面对 Swoole 和 Workerman 进行详细比较。

一、PHP-FPM：同步阻塞模型的代表

PHP-FPM 是目前最常见的 PHP 处理模式，适用于大多数 Web 应用，但它的同步阻塞模型有明显的性能瓶颈。请求处理流程大致如下：

客户端发起请求，通过 Web 服务器（如 Nginx、Apache）传递给 PHP-FPM。
PHP-FPM 创建新进程处理请求，每个进程独立解析、执行脚本。
同步阻塞执行：遇到 IO 操作时（如数据库查询、文件读写），整个进程会等待操作完成后继续执行。
请求结束，PHP-FPM 销毁进程或返回进程池，响应结果通过 Web 服务器传递给客户端。

PHP-FPM 每次请求都需要启动新的 PHP 进程，造成频繁的进程创建和销毁开销，尤其在高并发场景下性能受限明显。

二、常驻进程的优势：Swoole 和 Workerman

相比 PHP-FPM，Swoole 和 Workerman 采用了常驻进程模式，避免了频繁的进程启动和销毁。它们的主要特点包括：

常驻进程：服务器启动后，进程常驻内存，所有请求都在同一进程内处理，大幅减少了 PHP-FPM 中频繁创建进程的开销。
异步非阻塞 IO：两者都通过异步 IO 处理任务，不会因为慢速操作（如数据库查询、文件操作）而阻塞整个进程，提升了并发处理能力。
高并发支持：相比 PHP-FPM 的同步阻塞模型，Swoole 和 Workerman 能够处理成千上万的并发请求，特别适合需要处理长连接和实时通信的应用场景。

三、Swoole 与 Workerman 的对比

尽管 Swoole 和 Workerman 都是常驻进程模式，它们在设计和实现上有不少区别。

Swoole：高性能与复杂性

底层实现：Swoole 使用 C 语言编写，性能极为强大，尤其在高并发场景下，Swoole 的协程机制能够充分利用 CPU 资源，避免阻塞。
协程支持：Swoole 提供了协程，允许开发者在编写同步代码的同时享受异步的性能。这种方式能够极大减少异步编程的复杂性，尤其适用于高并发任务。
学习曲线：由于底层实现复杂，且文档相对晦涩，对于没有 C 语言背景的开发者来说，修改 Swoole 的底层代码不太友好，但它的团队响应及时。

Workerman：简洁与易用性

纯 PHP 实现：Workerman 完全用 PHP 实现，开发者无需学习 C 语言，修改和扩展也相对简单，更适合快速开发和维护。
性能适中：虽然 Workerman 的性能上限不如 Swoole，但对于大部分中小型项目，Workerman 的性能已经足够，且由于没有复杂的底层优化，调试和维护更加容易。
使用场景：适用于中等并发场景，如 WebSocket、实时推送等应用，尤其适合中小型项目开发。

四、Swoole 与 Workerman 相比 PHP-FPM 的优势

并发处理能力提升

在传统的 PHP-FPM 中，每个请求都需要启动一个独立的进程，这在高并发场景下会造成大量的资源开销。而 Swoole 和 Workerman 的常驻进程模式允许多个请求在同一进程中处理，显著提升了并发处理能力。Swoole 的协程机制进一步增强了处理大量并发连接时的性能。

异步非阻塞 IO

Swoole 和 Workerman 都支持异步非阻塞 IO，当遇到慢速的 IO 操作（如数据库查询、文件读写）时，不会阻塞整个进程，这意味着即使在高负载下，服务器也能保持高效响应。而在 PHP-FPM 中，慢速 IO 会阻塞整个进程，导致系统吞吐量大幅下降。

长连接与实时应用支持

常驻进程模式的框架特别适合处理长连接，比如 WebSocket 和聊天服务。PHP-FPM 因为每个请求都需要重新创建进程，无法很好地支持这些场景。而 Swoole 和 Workerman 都能够处理持久的长连接，适用于实时通信和推送服务。

五、总结：如何选择适合的框架？

性能与复杂度的平衡：如果你的项目对性能有极高要求，且团队具备一定的 C 语言能力，可以选择 Swoole，尤其在需要处理大量并发或复杂网络协议时，Swoole 的协程和底层优化会带来极大优势。如果你的项目规模较小或中等，Workerman 是更为简洁易用的选择，纯 PHP 实现让它更加容易维护，同时也能提供不错的并发处理能力。
项目类型：如果你的应用是传统的 Web 应用（如电商、博客等），PHP-FPM 已经足够处理。如果你需要处理长连接、实时推送或高并发服务，常驻进程的 Swoole 和 Workerman 是更合适的选择。最终，选择 Swoole 还是 Workerman，取决于项目的复杂性和团队的技术背景。如果你的应用需要极致的性能优化，可以考虑 Swoole；如果追求简单高效的开发体验，Workerman 是不错的选择。

Progressive Web App (PWA)：现代网页应用的进化

Mon, 21 Oct 2024 07:30:26 GMT

随着网络技术的进步，网页应用变得越来越强大。今天，我们可以通过一种被称为 Progressive Web App (PWA) 的技术，将网页应用提升到接近原生应用的体验。那么，什么是 PWA？它能为我们带来什么？又该如何实现它呢？本文将为你一一解答。

什么是 Progressive Web App (PWA)？

Progressive Web App，即渐进式网页应用，是一种结合了网页和原生应用优势的技术，旨在为用户提供类似原生应用的用户体验。传统网页应用虽然跨平台，但在体验上往往不如原生应用，而 PWA 通过现代 Web 技术弥补了这一差距，允许开发者构建能够离线访问、支持推送通知、并可以安装到主屏幕上的应用。

PWA 不仅保持了网页应用无需下载和安装的优势，还让用户在不同设备上获得流畅的一致体验，无论是桌面浏览器还是移动设备，PWA 都能自动适配。

Progressive Web App 能做什么？

PWA 在用户体验方面实现了多种原生应用的功能，包括：

离线访问：通过缓存技术，PWA 能够在无网络连接时继续工作。
推送通知：支持实时推送通知，让用户保持与应用的互动。
安装到主屏幕：用户可以将 PWA 添加到主屏幕，无需访问浏览器地址栏。
全屏运行：PWA 可以像原生应用一样在全屏模式下运行，隐藏浏览器 UI。
自动更新：应用可以自动在后台获取最新版本，而无需用户手动更新。
性能优化：PWA 通过响应式设计和快速加载的技术，提供流畅的用户体验。

这些特性不仅为用户带来了便利，也大大降低了开发者的跨平台开发成本。通过一次开发，PWA 能够在不同操作系统上提供一致的体验。

Progressive Web App 的特点

PWA 是基于一系列现代 Web 技术的集合，它具备以下几个显著特点：

渐进式增强：PWA 依赖现代浏览器的能力，但在旧版本浏览器上依然可以正常工作。
响应式设计：PWA 能自动适配各种屏幕大小，从手机到桌面，用户都能获得流畅的体验。
离线能力：通过 Service Worker 技术，PWA 可以缓存静态资源，在网络不稳定时也能继续使用。
安全性：PWA 必须通过 HTTPS 提供服务，确保数据传输安全。
安装性：用户可以将 PWA 添加到主屏幕，体验上与原生应用无异。
轻量级：PWA 不需要占用大量存储空间，启动速度快，同时也没有应用商店的审查流程。

如何实现 Progressive Web App？

实现一个 PWA 并不复杂，只需要几步即可将现有的网页应用转变为 PWA。

创建 Web App Manifest

首先，需要创建一个 manifest 文件，这是一个 JSON 文件，用来定义应用的图标、名称、启动 URL 以及显示方式等。例如：

{
  "name": "PWA示例",
  "short_name": "PWA",
  "start_url": "/index.html",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "icons": [
    {
      "src": "/images/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/images/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

将此文件命名为 manifest.json，并在你的 HTML 页面中引入：

<link rel="manifest" href="/manifest.json" />

注册 Service Worker

Service Worker 是 PWA 的核心，它是一种能够在后台运行的脚本，负责离线缓存和网络请求拦截。你可以创建一个简单的 service-worker.js 文件，用来缓存应用的静态资源：

self.addEventListener('install', (event) => {
  event.waitUntil(
    caches.open('pwa-cache').then((cache) => {
      return cache.addAll(['/', '/index.html', '/styles.css', '/script.js'])
    })
  )
})

self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request).then((response) => {
      return response || fetch(event.request)
    })
  )
})

在你的应用中注册这个 Service Worker：

if ('serviceWorker' in navigator) {
  navigator.serviceWorker
    .register('/service-worker.js')
    .then((registration) => {
      console.log('Service Worker 注册成功，作用域:', registration.scope)
    })
    .catch((error) => {
      console.log('Service Worker 注册失败:', error)
    })
}

确保通过 HTTPS 提供服务

为了保证安全性，PWA 必须通过 HTTPS 提供服务。这可以通过配置 SSL 证书来实现

优化用户体验

可以通过 meta 标签优化 PWA 在 iOS 设备上的显示效果，例如：

<meta name="apple-mobile-web-app-capable" content="yes" />
<meta name="apple-mobile-web-app-status-bar-style" content="black" />
<link rel="apple-touch-icon" href="/images/icon-192x192.png" />

总结

Progressive Web App (PWA) 让开发者能够构建跨平台、功能强大且用户体验接近原生应用的网页应用。通过使用 Web App Manifest、Service Worker 以及 HTTPS，你可以轻松将现有网页转变为 PWA，为用户提供离线支持、推送通知、快速加载等功能。

PWA 的出现标志着网页应用体验的巨大飞跃。无论是希望降低开发成本的企业，还是希望提升用户体验的开发者，PWA 都是一个值得关注和实施的技术方案。

定期备份数据库：基于 Shell 脚本的自动化方案

Sun, 20 Oct 2024 10:55:46 GMT

数据库备份这件事，说实话，我一直没怎么上心。平时服务器跑得好好的，谁会想着备份呢？直到某天真出问题了，才意识到自己平时有多“懒”。

我相信很多人跟我一样，觉得这东西看起来麻烦，等到数据库挂了、数据丢失了，才感叹自己怎么就没提前准备好呢？

有一次数据库问题搞得我手忙脚乱，最后还好有个朋友给了我个备份文件，才算是有惊无险。

经历了这次以后，我决定不能再拖了，必须把备份这事儿自动化起来。所以，我写了一个简单的 Shell 脚本，每天自动帮我把数据库备份好，还自动传到远程服务器上，再也不用担心数据丢失了。

今天就把这个脚本分享出来，或许能帮到和我一样平时“佛系”的朋友。脚本简单好用，拿来直接用就行，具体的实现逻辑也不复杂，如果你有其他需求，可以自行优化。

备份脚本内容

#!/bin/bash

# MySQL连接参数（可以使用 ~/.my.cnf 文件代替）
DB_USER="数据库账号"
DB_PASS="数据库密码"

# 备份目录
BACKUP_DIR="/数据库备份目录"

# 日志文件路径
CURRENT_DATE=$(date +'%Y%m%d%H%M%S')
LOG_FILE="/数据库备份日志目录/$CURRENT_DATE.log"

# 目标服务器的 SSH 用户名和 IP 地址，如果不需要同步到其他服务器则不需要填写
# -----------------------------
REMOTE_USER="" # 目标服务器账号
REMOTE_HOST="" #目标服务器IP
REMOTE_DIR="" # 目标服务器存储路径
# -----------------------------

# SSH 连接超时时间（单位：秒）
SSH_CONNECT_TIMEOUT=10

# 创建备份和日志目录（如果不存在）
mkdir -p "$BACKUP_DIR"
mkdir -p "$(dirname "$LOG_FILE")"

# 获取所有数据库列表
DATABASES=$(mysql -e "SHOW DATABASES;" | grep -Ev "(Database|information_schema|performance_schema|mysql)")

# 循环备份每个数据库
BACKUP_FILES=()
for DB in $DATABASES; do
    BACKUP_FILE="$BACKUP_DIR/$DB-$CURRENT_DATE.sql.gz"
    echo "$(date +%Y%m%d%H%M%S) 备份数据库 $DB 到文件 $BACKUP_FILE" >> $LOG_FILE
    if ! mysqldump -u $DB_USER -p$DB_PASS --single-transaction --databases $DB | gzip > $BACKUP_FILE; then
        echo "$(date +%Y%m%d%H%M%S) 备份数据库 $DB 失败" >> $LOG_FILE
        continue  # 跳过当前数据库，继续备份其他数据库
    fi
    echo "$(date +%Y%m%d%H%M%S) 备份完成" >> $LOG_FILE
    BACKUP_FILES+=($BACKUP_FILE)
done

# 创建远程备份目录
if [ -n "$REMOTE_USER" ] && [ -n "$REMOTE_HOST" ] && [ -n "$REMOTE_DIR" ]; then
    ssh -o ConnectTimeout=$SSH_CONNECT_TIMEOUT $REMOTE_USER@$REMOTE_HOST "mkdir -p $REMOTE_DIR"

    # 批量传输备份文件
    if [ ${#BACKUP_FILES[@]} -gt 0 ]; then
        echo "$(date +%Y%m%d%H%M%S) 将备份文件发送到远程服务器..." >> $LOG_FILE
        scp -o ConnectTimeout=$SSH_CONNECT_TIMEOUT ${BACKUP_FILES[@]} $REMOTE_USER@$REMOTE_HOST:$REMOTE_DIR
        echo "$(date +%Y%m%d%H%M%S) 备份文件发送完成" >> $LOG_FILE
    fi

    # 删除本地备份文件
    echo "删除本地备份文件..." >> $LOG_FILE
    for BACKUP_FILE in "${BACKUP_FILES[@]}"; do
        rm -f $BACKUP_FILE
    done
    echo "本地备份文件删除完成" >> $LOG_FILE
fi

# 完成
echo "------------------------------" >> $LOG_FILE

关于同步到其他服务器

如果需要同步到远程服务器的话，为了避免每次执行脚本时都手动输入密码，可以使用 SSH 密钥对（公钥和私钥）来实现免密登录

具体步骤如下：

在数据库所在机器上生成 SSH 密钥对

首先，确保你在数据库机器上没有已有的 SSH 密钥对（如果有，跳过这一步）。在 A 机器上运行以下命令来生成一个新的 SSH 密钥对：

ssh-keygen -t rsa -b 2048

按照提示操作，默认保存路径是 ~/.ssh/id_rsa，可以选择直接按 Enter 使用默认路径。生成密钥后，你会得到两个文件：

id_rsa：私钥文件，保存在数据库所在机器上。
id_rsa.pub：公钥文件，用于复制到需要同步的机器。

将公钥复制到需要同步的机器

你需要将 id_rsa.pub 的内容复制到需要同步的机器上，添加到目标用户的 ~/.ssh/authorized_keys 文件中。你可以使用以下命令来实现这一点：

ssh-copy-id -i ~/.ssh/id_rsa.pub 需要同步的机器目标用户@需要同步的机器的IP

如果你的目标用户在需要同步的机器上是 remote_user，IP 地址是 192.168.1.100，那么命令会是：

ssh-copy-id -i ~/.ssh/id_rsa.pub remote_user@192.168.1.100

执行后，你将被提示输入需要同步的机器的密码，输入一次后，公钥将被自动添加到需要同步的机器上的 ~/.ssh/authorized_keys 文件中。

验证免密登录

此时，你应该能够从数据库所在机器免密登录到需要同步的机器，试试这个命令：

ssh remote_user@192.168.1.100

如果成功登录且没有要求输入密码，则说明配置成功。

总结

虽然数据库备份在日常中似乎并不重要，但等到真正出问题时，备份的价值就凸显出来了。

有了这个脚本后，我再也不用手动备份数据库，也不怕丢数据了。

希望这份脚本能帮到大家。

Laravel Eloquent 关联与 JOIN 查询：性能权衡与最佳实践

Fri, 18 Oct 2024 03:19:06 GMT

Laravel 是一个优秀的 PHP 框架，其强大的 Eloquent ORM 提供了简洁而灵活的模型关系定义。然而，在处理大规模数据时，如何权衡 Eloquent 关联与数据库 JOIN 查询的性能问题，往往是开发者关注的焦点。

在这篇文章中，我们将探讨 Eloquent 模型关联的工作原理，解释延迟加载（Lazy Loading）和预加载（Eager Loading），并比较它们与 JOIN 查询的性能差异。最后，我们将讨论一些在大数据集下提升查询效率的最佳实践。

Eloquent 关联的工作原理

Laravel 提供了多种 Eloquent 关联方式，包括一对一（One-to-One）、一对多（One-to-Many）、多对多（Many-to-Many）以及多态关联（Polymorphic Relations）。这些关系可以让我们通过模型直接获取相关数据。

一个常见的示例是用户模型与手机号码模型之间的一对一关联：

class User extends Model {
    public function phone() {
        return $this->hasOne(Phone::class);
    }
}

我们可以通过 $user->phone 来获取关联的手机号码。在这个过程中，Eloquent 默认使用 延迟加载（Lazy Loading），意味着只有在访问 $user->phone 时，才会发出 SQL 查询。这种方式在小数据集下运行良好，但在处理大量数据时可能会带来性能问题。

延迟加载的性能问题

假设你有 10,000 名用户，并希望获取每个用户的手机号码：

$users = User::all();
foreach ($users as $user) {
    echo $user->phone->number;
}

在这里，Laravel 会执行 1 次查询获取所有用户的数据，然后为每个用户单独执行 1 次查询获取关联的 phone 数据。也就是说，总共会执行 10,001 次查询。这种查询模式被称为 N+1 查询问题，会对数据库性能产生很大的影响。

预加载（Eager Loading）

为了避免 N+1 查询问题，Laravel 提供了 预加载（Eager Loading）。通过 with 方法，我们可以一次性将所有关联的数据一起查询出来：

$users = User::with('phone')->get();
foreach ($users as $user) {
    echo $user->phone->number;
}

在这个例子中，Laravel 会执行两次查询：

一次查询用户表，获取所有用户；
一次查询手机号码表，获取所有用户的手机号码。

即使有 10,000 个用户，也只会执行 2 次查询，大大减少了查询次数。

Eloquent 关联与 JOIN 查询的对比

有时候，你可能会考虑直接使用 SQL 的 JOIN 语句将数据一次性查询出来：

$users = User::join('phones', 'users.id', '=', 'phones.user_id')
    ->select('users.*', 'phones.number')
    ->get();

这种情况下，数据库会执行一个 INNER JOIN 操作，将 User 和 Phone 的数据一次性查询出来。在某些场景下，使用 JOIN 查询会更高效，特别是当你只需要获取部分关联数据而非整个关联模型时。

性能对比

Eloquent 预加载：适用于需要访问完整模型数据的场景。它避免了 N+1 查询问题，并保持了 Eloquent 模型的简洁性和可读性。
JOIN 查询：适用于你只需要某些特定字段而不需要加载整个关联模型的情况。JOIN 操作在数据库层面完成，性能上可能更优，尤其是在进行过滤、排序或聚合操作时。

如何选择？

Eloquent 预加载：如果你需要使用 Eloquent 提供的所有功能，并且关联模型的数据较复杂，那么 with 预加载是一个很好的选择，它在避免 N+1 查询问题的同时保留了 ORM 的灵活性。
JOIN 查询：当你需要最大化性能，且只需要关联表的部分字段时，直接使用 JOIN 查询会更高效。

性能优化建议

在处理大数据集时，除了选择合适的查询方式外，还有一些其他的优化建议可以帮助你提升性能：

使用批量处理 (Chunk)

如果你需要处理大量数据，Laravel 提供了 chunk 方法，可以将大数据集分批处理，避免内存占用过高：

User::with('phone')->chunk(1000, function ($users) {
    foreach ($users as $user) {
        echo $user->phone->number;
    }
});

通过将查询结果分批处理，你可以有效减少内存的使用，特别是在处理上万条记录时。

添加数据库索引

确保为外键字段添加索引是提升查询性能的关键。例如，在 Phone 表的 user_id 字段上添加索引，可以加速关联查询，特别是当数据量较大时。

考虑缓存

对于频繁查询的数据，可以考虑使用 Laravel 的缓存功能来减少数据库查询次数。通过缓存关联数据，可以避免反复的数据库查询，从而提高性能。

结论

在 Laravel 中，Eloquent 关联为我们提供了简洁的 ORM 操作方式，但在处理大数据集时，性能问题不容忽视。为了解决这些问题，我们可以选择使用 Eloquent 的预加载 (with) 或直接使用数据库的 JOIN 查询，具体取决于数据量和查询需求。

通过正确选择查询方式、使用批量处理、优化数据库索引以及引入缓存等技术手段，我们可以在享受 Eloquent 便利性的同时确保应用的性能表现。

从零开始创建属于自己的 Composer 库

Thu, 17 Oct 2024 12:24:20 GMT

Composer 是 PHP 领域最流行的依赖管理工具，它使得管理项目依赖变得轻松简单。然而，除了使用现有的包，我们也可以创建和发布属于自己的 Composer 包。在这篇文章中，我将带你一步一步完成从零开始创建并发布一个自己的 Composer 包的流程。

创建项目

在你的工作目录下创建一个新的文件夹作为你的包：

mkdir project
cd project

初始化 Composer

在项目目录中运行以下命令以生成 composer.json 文件：

composer init

确保您已经安装了 Composer，如果尚未安装，可以通过 Composer 的官方网站获取详细的安装说明。

composer init 执行后会需要填写一些内容，皆指帮助您生成 composer.json 文件，所以不需要过于在意，后期也可以直接修改 composer.json 文件，大概内容如下：

提交到 GitHub 或其他版本控制系统

将你的项目提交到 GitHub 或其他版本控制系统。确保你的 composer.json 文件在根目录下。

建议上传到 GitHub 中，关于无法访问的问题详见如何实现科学上网

发布到 Packagist

在 Packagist 上注册一个帐户。
登录后，点击右上角的 “Submit” 按钮后提交自己的 Git 链接即可发布

后续建议

发布版本

为什么要在 GitHub 上发布版本？

为了管理每次更新的内容，建议在 GitHub 中发布版本，这样做有以下几种好处

可追溯性：每个版本都可以追踪到特定的提交，方便用户查看变更。
文档：可以为每个版本添加发布说明，告知用户新版本的功能和修复。
整合：与 Composer 的版本管理系统无缝集成，方便用户在 Composer 中安装特定版本。

如何在 GitHub 上发布版本？

创建一个标签：

## 在终端中导航到你的项目目录，并确保在你想要发布的版本上
git checkout main
## 创建一个 Git 标签，命名为你的版本号（例如 v1.0.0）
git tag v1.0.0
## 将标签推送到 GitHub
git push origin v1.0.0

在 GitHub 上创建发行版：

登录到你的 GitHub 仓库。
点击“Releases”选项卡。
点击“Draft a new release”按钮。
选择刚刚创建的标签（例如 v1.0.0）。
填写发行说明，简要描述该版本的新功能、修复或变更。
点击“Publish release”按钮。

维护版本

每次更新你的代码并希望发布新版本时，重复以上步骤创建新的标签和发行版。

你可以使用语义版本控制（如 MAJOR.MINOR.PATCH）来管理版本号。

服务器文件变更同步小脚本

Mon, 14 Oct 2024 08:15:41 GMT

最近发现用于为用户提供下载服务的服务器带宽承载压力逐渐增大，我建议使用阿里云的 OSS 来解决这个问题，毕竟 OSS 具备高效的存储和分发能力。

然而，老板坚持选择多台服务器结合 CDN 进行内容分发。

虽然这种方案可以缓解部分流量压力，但每次有内容更新时都需要手动同步到每台服务器。

为了简化这一过程，我编写了一个自动同步的小脚本，来实现内容的快速分发

话不多说直接上代码

当前脚本为检测特定目录下.apk文件的变更，根据实际需要调整第66行即可

package main

import (
    "fmt"
    "io"
    "log"
    "sort"
    "os"
    "os/exec"
    "path/filepath"
    "strings"
    "time"

    "github.com/fsnotify/fsnotify"
)

var lastEventTime = make(map[string]time.Time)
var debounceDuration = 10 * time.Second // 可调整的去重时间间隔

// 监测路径
var rootDir = "/www/wwwroot/ftp"

// 目标服务器列表
var servers = []string{
    "同步服务器1登录账号@同步服务器1IP:/",
    "同步服务器2登录账号@同步服务器2IP:/",
    "同步服务器3登录账号@同步服务器3IP:/",
    "root@47.98.152.221:/",
}

// 子目录与目标路径的映射
var pathMap = map[string]string{
    "本地服务器路径标识":     "同步服务器路径（从跟路径起算）",
    "本地服务器路径标识":     "同步服务器路径（从跟路径起算）",
    "Anxin":               "www/wwwroot/Anxin",
}

func main() {
    // 设置日志输出到文件
    logFile, err := os.OpenFile("script.log", os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0644)
    if err != nil {
        log.Fatalf("无法打开日志文件: %v", err)
    }
    defer logFile.Close()
    log.SetOutput(logFile)

    // 创建文件监控器
    watcher, err := fsnotify.NewWatcher()
    if err != nil {
        log.Fatal(err)
    }
    defer watcher.Close()
    done := make(chan bool)
    go func() {
        for {
            select {
            case event, ok := <-watcher.Events:
                if !ok {
                    return
                }
                // 监测更多事件类型
                if (event.Op&fsnotify.Write == fsnotify.Write ||
                    event.Op&fsnotify.Create == fsnotify.Create ||
                    event.Op&fsnotify.Rename == fsnotify.Rename ||
                    event.Op&fsnotify.Chmod == fsnotify.Chmod) &&
                    strings.HasSuffix(event.Name, ".apk") { // 判断是否是.apk文件
                    // 去重逻辑
                    if lastTime, exists := lastEventTime[event.Name]; exists {
                        if time.Since(lastTime) < debounceDuration {
                            // 如果上次处理时间在去重时间间隔内，跳过此事件
                            continue
                        }
                    }
                    lastEventTime[event.Name] = time.Now()
                    log.Printf("监测到文件变更: %s, 事件类型: %v\n", event.Name, event.Op)
                    // 调用 scp 同步文件
                    err := syncFile(event.Name)
                    if err != nil {
                        log.Printf("文件同步失败: %v", err)
                    }
                }
            case err, ok := <-watcher.Errors:
                if !ok {
                    return
                }
                log.Println("错误:", err)
            }
        }
    }()
    // 监控目录及子目录
    err = filepath.Walk(rootDir, func(path string, info os.FileInfo, err error) error {
        if err != nil {
            return err
        }
        if info.IsDir() {
            err = watcher.Add(path)
            if err != nil {
                log.Fatal(err)
            }
        }
        return nil
    })
    if err != nil {
        log.Fatal(err)
    }
    <-done
}

// syncFile 使用 scp 同步文件到多台服务器的不同路径，并复制到本地对应目录
func syncFile(filePath string) error {
    // 找到文件所属的子目录
    subDir := ""
    // 先按路径长度降序排序，确保长名称优先匹配
    for _, dir := range sortedKeys(pathMap) {
        if strings.Contains(filePath, dir) {
            subDir = dir
            break
        }
    }
    if subDir == "" {
        return fmt.Errorf("文件没有匹配的目标目录: %s", filePath)
    }
    // 获取同步目标路径
    targetPath := pathMap[subDir]
    fmt.Println("匹配目录:", targetPath)

    // 执行 scp 命令同步文件到每个服务器
    for _, server := range servers {
        // 组合目标路径
        destination := fmt.Sprintf("%s%s", server, targetPath)
        // 构建并执行 scp 命令
        cmd := exec.Command("scp", filePath, destination)
        // 捕获输出和错误信息
        output, err := cmd.CombinedOutput()
        if err != nil {
            log.Printf("执行 scp 命令失败: %v, 输出: %s", err, output)
            return err
        }
        log.Printf("文件 %s 同步到 %s\n", filePath, destination)
    }

    // 复制文件到本地对应的目录
    localDestination := filepath.Join(rootDir, targetPath)
    err := copyFileToLocal(filePath, localDestination)
    if err != nil {
        log.Printf("文件复制到本地失败: %v", err)
        return err
    }
    log.Printf("文件 %s 复制到本地目录 %s\n", filePath, localDestination)

    return nil
}

// copyFileToLocal 将文件复制到本地目录
func copyFileToLocal(srcPath, dstDir string) error {
    // 确保目标目录存在
    if err := os.MkdirAll(dstDir, os.ModePerm); err != nil {
        return fmt.Errorf("创建本地目录失败: %v", err)
    }
    // 获取文件名
    fileName := filepath.Base(srcPath)
    // 目标文件路径
    dstPath := filepath.Join(dstDir, fileName)
    // 打开源文件
    srcFile, err := os.Open(srcPath)
    if err != nil {
        return fmt.Errorf("打开源文件失败: %v", err)
    }
    defer srcFile.Close()
    // 创建目标文件
    dstFile, err := os.Create(dstPath)
    if err != nil {
        return fmt.Errorf("创建目标文件失败: %v", err)
    }
    defer dstFile.Close()
    // 复制文件内容
    _, err = io.Copy(dstFile, srcFile)
    if err != nil {
        return fmt.Errorf("复制文件内容失败: %v", err)
    }
    return nil
}

// sortedKeys 返回按长度降序排序的键列表
func sortedKeys(m map[string]string) []string {
    keys := make([]string, 0, len(m))
    for k := range m {
        keys = append(keys, k)
    }
    sort.Slice(keys, func(i, j int) bool {
        return len(keys[i]) > len(keys[j])
    })
    return keys
}

记录一次对CC攻击的处理

Tue, 08 Oct 2024 04:47:32 GMT

最近，我的 PHP 系统遭遇了一次 CC 攻击。这次攻击并不算特别猛烈，但足以对服务器造成明显的压力。由于从本质上来说，CC 攻击和DDoS 攻击都属于流量型和资源耗尽型的攻击，完全防御它们是不太现实的，尤其是在攻击量足够大的情况下。因此，结合这次的实际情况，系统做了一些调整和优化，以下是我尝试有效的几种应对策略。

使用阿里云全站加速（DCDN）

现在叫边缘安全加速（ESA）。

这是一个非常经济实惠的解决方案，在加速访问的同时，CDN 还能帮助隐藏服务器的真实 IP 地址

这对于防止 DDoS 攻击非常重要。因为 DDoS 攻击大多数是基于 IP 地址进行的，一旦服务器的 IP 地址暴露，就很容易成为攻击目标。

而通过 CDN，攻击者只能找到 CDN 节点，攻击者获取不到源服务器的 IP。这有效减轻了 DDoS 攻击的可能性，让系统能够专注于应对应用层面的 CC 攻击。

阿里云的 WAF（Web 应用防火墙）

WAF 的核心功能就是在请求到达服务器之前进行一次安全检查，从而过滤掉明显的恶意请求。

区域封禁+限速器组合使用，一方面可以封禁非业务地区（例如不存在海外业务时候无需处理来自境外的请求），一方面可以过滤掉明显异常的高频请求。

这一步非常关键，因为 CC 攻击的目的是消耗服务器资源，一旦服务器资源被耗尽，整个系统就会陷入瘫痪。而 WAF 能够在流量进入服务器之前过滤掉这些恶意流量，从源头上减少服务器的压力。

使用 Webman 等高性能框架

除了外部的防护措施，高性能框架也是应对攻击的关键。在这次攻击处理中，我使用了 Webman 框架，这是一种常驻内存的 PHP 高性能框架。

相比传统依靠 FPM（FastCGI Process Manager），每个请求都会重新加载应用程序和 PHP 环境，的框架

Webman 使用了常驻内存模型，意味着 PHP 和框架只会在服务器启动时加载一次，之后的每个请求直接使用已经加载的内存，性能极高，可以显著提高每秒请求处理能力（QPS），使得服务器能在同等资源下承受更多的请求。

Webman 在这次攻击中表现非常出色，在高并发下保持了较高的响应速度。即使是在遭遇 CC 攻击的情况下，服务器也没有完全被压垮，保证了部分正常用户的访问。

加密与鉴权机制

在接口设计上，我建议对所有请求都要做严格的加密与鉴权处理。这样即使攻击者发起了模拟请求，只要没有通过鉴权，他们就无法真正调用到系统的核心逻辑。

通常推荐在加密数据中加入时间戳，这样每个请求都是一次性的。

一方面可以防止因抓包重复请求消耗服务器资源的情况发生。

另一方面因为时间的变化，即使是相同的内容在进行对称加密时每次的加密信息也不同，这可以有效增加加密信息被破解的难度。

只有验证通过的请求才会被进一步处理。这个设计大大降低了恶意请求对系统的影响。

核心防护思路

经过这次攻击处理，我总结出一个核心思路：尽量不要让恶意请求真正触发服务器资源的消耗。能在外部拦住的请求就尽量在外部拦截，无法拦住的请求则依赖系统内部的鉴权与加密机制进行二次过滤。

具体来说，通过 CDN 隐藏 IP，利用 WAF 过滤恶意流量，在应用层面通过高性能框架提高系统抗压能力，再配合加密和鉴权机制来阻止模拟请求成功，这些措施都可以有效减少 CC 攻击对服务器的影响。

总结

在面对 CC 攻击时，我们不可能做到百分之百的防御，尤其是当攻击量足够大时。但通过合理的防护手段，我们可以有效减少攻击带来的影响，保护系统的稳定运行。

我相信只要合理利用这些工具，并根据业务需求做出相应的调整，任何开发者都可以在遭遇攻击时尽量减少损失。

Webman 错误控制

Fri, 04 Oct 2024 07:49:36 GMT

在 Webman 中，控制错误返回可以通过全局异常处理器（ExceptionHandler）来处理。你可以自定义异常处理逻辑，根据不同的异常类型或错误，返回不同的 HTTP 响应状态码和错误信息。以下是一个实现方式的示例：

自定义全局异常处理器

你可以定义自己的异常处理器，例如创建一个 app/exception/Handler.php ，继承 Webman 提供的 ExceptionHandlerInterface：

<?php
namespace app\exception;

use Throwable;
use Webman\Http\Response;
use Webman\Http\Request;
use Webman\Exception\ExceptionHandlerInterface;

class Handler implements ExceptionHandlerInterface
{
    // 定义不需要记录日志的异常类型
    public $dontReport = [
        // 在这里可以定义不需要记录日志的异常类型
        \Illuminate\Validation\ValidationException::class,
        // 例如自定义业务逻辑异常
        \app\exception\BusinessException::class,
    ];

    /**
     * 处理异常的方法
     *
     * @param Request $request
     * @param Throwable $exception
     * @return Response
     */
    public function render(Request $request, Throwable $exception): Response
    {
        // 检查是否为自定义的业务异常
        if ($exception instanceof \app\exception\BusinessException) {
            return response(json(['error' => $exception->getMessage()], 400));
        }

        // 默认返回500错误
        return response(json(['error' => 'Server Error'], 500));
    }

    /**
     * 记录异常日志的方法
     *
     * @param Throwable $exception
     * @return void
     */
    public function report(Throwable $exception)
    {
        // 如果异常不在 dontReport 中，就记录日志
        if (!$this->shouldntReport($exception)) {
            echo $exception; // 这里可以使用你喜欢的日志系统记录错误
        }
    }

    /**
     * 判断是否应该记录异常
     *
     * @param Throwable $exception
     * @return bool
     */
    protected function shouldntReport(Throwable $exception): bool
    {
        foreach ($this->dontReport as $type) {
            if ($exception instanceof $type) {
                return true;
            }
        }
        return false;
    }
}

在配置文件中指定异常处理器

在 config/exception.php 中，你可以指定这个异常处理器：

return [
    'exception_handler' => app\exception\Handler::class,
];

自定义异常类

你可以根据需求定义自己的业务异常类，例如：

<?php
namespace app\exception;

use Exception;

class BusinessException extends Exception
{
    public function __construct($message = "业务逻辑异常", $code = 400)
    {
        parent::__construct($message, $code);
    }
}

返回自定义错误响应

当某个操作出现业务错误时，你可以抛出自定义异常，比如：

use app\exception\BusinessException;

throw new BusinessException("自定义的业务错误信息", 400);

这样，Webman 会根据你在全局异常处理器中定义的逻辑，返回相应的错误信息和 HTTP 状态码。

总结

通过自定义全局异常处理器，你可以灵活地控制 Webman 应用中的错误返回，能够根据不同的异常类型返回不同的错误信息，并记录相应的日志。

Bilibili直播监控实现

Sun, 15 Oct 2023 01:18:51 GMT

哔哩哔哩直播监控实现

本文讲述了如何从服务器端的方向，实现对哔哩哔哩直播间的弹幕监控，进房提醒，礼物自动答谢等功能的实现，以及自动录播并分段上传

直播弹幕监控，自动欢迎进房，自动答谢礼物等功能来自 GitHub 中公开的项目：弹幕姬点击进入 GitHub

自动录播，视频分段来自 GitHub 中公开的项目：录播姬点击进入 GitHub

自动投稿来自于 GitHub 中公开的项目：biliup-rs 点击进入 GitHub

本文主要在于记录这些项目部署的全过程，以及一些额外小功能的实现原理

录播姬

下载

可以通过 GitHub Release 页面中获取自己需要的版本进行下载

无特殊情况下，使用 BililiveRecorder-CLI-linux-x64 版本即可

| 操作系统 | 架构 | 下载链接 | | :------- | :---- | :----------------------------------- | | Linux | x64 | BililiveRecorder-CLI-linux-x64.zip | | Linux | arm32 | BililiveRecorder-CLI-linux-arm.zip | | Linux | arm64 | BililiveRecorder-CLI-linux-arm64.zip | | Windows | x64 | BililiveRecorder-CLI-win-x64.zip | | macOS | x64 | BililiveRecorder-CLI-osx-x64.zip | | macOS | arm64 | BililiveRecorder-CLI-osx-arm64.zip |

安装

下载并解压压缩包，以 Linux x64 为例：

mkdir <录播姬目录>
cd <录播姬目录>
# wget https://下载链接
unzip <下载到的 zip 压缩包>

解压完成后，记得检查确认文件夹中的 BililiveRecorder.Cli 是否带有可执行权限，如果没有的话使用以下命令添加可执行权限：chmod +x BililiveRecorder.Cli

确认录播姬可以运行、并检查版本号

./BililiveRecorder.Cli --version

后续录播姬的控制均由 BililiveRecorder.Cli 来处理，为了方便命令行的使用，可以将该文件缩写为其他名称，例如：brec ，方法如下：mv BililiveRecorder.Cli brec

录播姬所有命令都可以加上 --help 查看帮助

运行

./brec run "工作目录"

# 侦听本机地址，只有本地可以访问
./brec run --bind "http://localhost:2356" "工作目录"

# 或者所有设备都可访问
./brec run --bind "http://*:2356" "工作目录"

# HTTP Basic 登陆
./brec run --bind "http://*:2356" --http-basic-user "用户名" --http-basic-pass "密码" "工作目录"

# 使用录播姬自己生成的自签名证书
./brec run --bind "https://*:2356" "工作目录"

# 使用 pem 格式的证书，和 Nginx Caddy 等软件的证书格式一致
./brec run --bind "https://*:2356" --cert-pem-path "证书文件路径" --cert-key-path "私钥文件路径" "工作目录"

# 使用带密码的私钥
./brec run --bind "https://*:2356" --cert-pem-path "证书文件路径" --cert-key-path "私钥文件路径" --cert-password "私钥密码" "工作目录"

# 使用 pfx 格式的证书
./brec run --bind "https://*:2356" --cert-pfx-path "证书文件路径" "工作目录"

# 使用带密码的证书
./brec run --bind "https://*:2356" --cert-pfx-path "证书文件路径" --cert-password "私钥密码" "工作目录"

后续

录播姬需要保持后台持续运行，建议增加至 systemd 中并设置开机自动启动

创建服务

新建一个文件 /etc/systemd/system/brec.service

[Unit]
Description=BililiveRecorder
After=network.target

[Service]
ExecStart=录播姬运行命令，注意使用根路径

[Install]
WantedBy=multi-user.target

重载服务

systemctl daemon-reload

设置开机自动启动

systemctl enable brec

禁止开机自动启动

systemctl disable brec

常用指令

# 查看运行状态
sudo systemctl status brec

# 启动
sudo systemctl start brec

# 停止
sudo systemctl stop brec

# 重启
sudo systemctl restart brec

其他

录播姬支持 webhook，部署成功后可以进行对应的设置可以在直播开始/结束，文件录制开始/结束等节点对配置地址进行通知点击查看相关文档

弹幕姬

该项目基于 Java 环境运行，安装前请先检查服务器是否安装 Java 以及检查 Java 的版本

建议 Java 版本 >= 1.8

Java 的安装方式网上有很多教程，本文不再中间描述，以 Centos 为例，官网下载对应的包

在 /etc/profile 中增加对应的环境变量即可

export JAVA_HOME=java目录
export PATH=$JAVA_HOME/bin:$PATH
export CLASSPATH=.:$JAVA_HOME/lib/dt.jar:$JAVA_HOME/lib/tools.jar
export JRE_HOME=$JAVA_HOME/jre

记得通过 source /etc/profile 来使环境变量生效

下载

可以通过 GitHub Release 页面中获取自己需要的版本进行下载

安装 & 运行

该项目无需安装，直接运行 .jar 包即可，例如：java -jar BilibiliDanmu.jar

需要关闭时，可以通过 fuser -k -n tcp 对应端口 来进行关闭

Biliup-rs

biliup-rs 是用 Rust 编写的，所以需要安装 Rust 才能编译它

## 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

## 更新 Rust
rustup update

安装

cargo install biliup

使用

可以通过执行命令：biliup -h 来查看可以进行的操作

USAGE:
    biliup [OPTIONS] <SUBCOMMAND>

OPTIONS:
    -h, --help                         Print help information
    -u, --user-cookie <USER_COOKIE>    登录信息文件 [default: cookies.json]
    -V, --version                      Print version information

SUBCOMMANDS:
    append    是否要对某稿件追加视频
    help      Print this message or the help of the given subcommand(s)
    login     登录B站并保存登录信息
    renew     手动验证并刷新登录信息
    show      打印视频详情
    upload    上传视频

其他

因为录播姬支持 webhook，当文件录制完成时可以触发回调

所以建议在本地做一个小脚本，当收到文件录制完成的通知时调用 biliup 上传录制完成的文件，实现自动上传

B 站投稿线路分析

B 站 tid 分区表

{
    "cmd":"POPULARITY_RED_POCKET_WINNER_LIST",
    "data":{
        "awards":{ ## 奖品数组
            "31212":{
                "award_big_pic":"https://i0.hdslb.com/bfs/live/9e6521c57f24c7149c054d265818d4b82059f2ef.png", ## 奖品图片
                "award_name":"打call", ## 奖品名称
                "award_pic":"https://s1.hdslb.com/bfs/live/461be640f60788c1d159ec8d6c5d5cf1ef3d1830.png", ## 奖品图片
                "award_price":500, ## 奖品价值，单位电池*100
                "award_type":1 ## 待观察
            },
            "31214":{
                "award_big_pic":"https://i0.hdslb.com/bfs/live/3b74c117b4f265edcea261bc5608a58d3a7c300a.png",
                "award_name":"牛哇",
                "award_pic":"https://s1.hdslb.com/bfs/live/91ac8e35dd93a7196325f1e2052356e71d135afb.png",
                "award_price":100,
                "award_type":1
            },
            "31216":{
                "award_big_pic":"https://i0.hdslb.com/bfs/live/cf90eac49ac0df5c26312f457e92edfff266f3f1.png",
                "award_name":"小花花",
                "award_pic":"https://s1.hdslb.com/bfs/live/5126973892625f3a43a8290be6b625b5e54261a5.png",
                "award_price":100,
                "award_type":1
            }
        },
        "lot_id":12803470, ## 红包id
        "total_num":8, ## 待观察，应该是奖品数量
        "version":1,
        "winner_info":[
            [
                100422246, ## 用户uid
                "呆呆是豆腐的好爸爸捏", ## 用户名称
                6549542, ## 待观察
                31212 ## 中奖礼物信息，对应礼物数组
            ],
            [
                244187937,
                "一哭二闹三上佑娅",
                6450325,
                31212
            ],
            [
                33452712,
                "纯爱猫猫丶",
                6537056,
                31214
            ],
            [
                258093224,
                "凌小辰是小雏楠",
                6464920,
                31214
            ],
            [
                512011712,
                "东哥不爱喝",
                6537057,
                31214
            ],
            [
                3494364166752651,
                "鹤九-z",
                6458205,
                31216
            ]
        ]
    },
    "is_report":false, ## 待观察
    "msg_id":"146118578543104", ## 待观察
    "send_time":1688832579071 ## 推送时间
}

星河避难所

一次被封 IP 之后：从 Shadowsocks 到 Xray Reality

安装 Xray

生成 UUID

生成密钥对

完善配置文件

启动 Xray

通过 Clash 连接

常见处理方式

常见匹配类型

示例配置

一点总结

从番剧墙到一个 Go CLI 工具

这个工具做了什么

为什么会想自己写

它解决的其实不是技术问题

关于我的番剧墙

写在最后

用 Go 实现一个可长期运行的 GitHub Webhook 服务实践

项目结构与职责划分

repository

service

handler

在 bootstrap 中组织依赖关系

双队列 Worker Pool 的并发调度模型

第一层：任务生产者

第二层：集中式调度器 + Worker Pool

第三层：结果处理器

Makefile 作为构建入口

使用 embed 将前端资源打包进二进制

写在最后

从“能写 Go”到“写得对 Go”：一名 PHP 开发者的补课与重构

写在前面

一、重新认识 Go

1. 为什么 Go 不适合用「脚本语言思维」去理解

2. Go 的编译模型、运行时与 PHP 的本质差异

3. Go 项目结构与 go mod 的真实作用

4. package、import 与依赖边界（为什么 Go 讨厌循环依赖）

二、值语义：PHP 开发者最容易踩的第一坑

5. struct 是值，不是对象

6. 函数参数传递：值拷贝 vs 指针

7. 返回 struct、返回指针、返回 interface 的区别

8. 方法接收者：值接收者 vs 指针接收者

9. 「什么时候必须用指针」的经验法则

三、指针：只学 Go 中真正需要的那一部分

​10. &​ 和 * 的真实含义

11. 指针并不是“性能优化工具”

12. nil 指针与零值的区别

13. 指针在业务代码中的合理边界

14. Go 为什么不鼓励随意暴露指针

四、slice：Go 中最“像魔法”的数据结构

15. slice 的底层结构：指针、长度、容量

16. slice ≠ array：为什么 append 会出问题

17. 扩容带来的引用断裂问题

18. slice 作为函数参数的常见误解

19. slice 在并发场景下的风险

五、map：看起来简单，实则暗雷密布

20. map 是引用类型，但不是并发安全

21. nil map vs make(map)

22. map 在函数间传递的行为

23. map 并发读写为什么会直接 panic

24. 使用 map 时的防御性写法

六、defer 与资源生命周期

25. defer 的执行时机与栈模型

26. defer + loop 的经典坑

27. defer 在 Web 请求中的正确使用方式

28. Go 中资源释放为什么必须显式

七、error：Go 的“显式异常系统”

29. error 是值，而不是异常

30. ​if err != nil 为什么是设计选择

31. 错误向上传递的最佳实践

32. panic、recover 的合理使用场景

33. 错误包装（wrap）与错误定位

八、Go 的并发模型：从根上和 PHP 不一样

34. goroutine 不是线程

35. GMP 调度模型的直觉理解

36. 为什么 Go 可以“随便起协程”

37. 并发 ≠ 更快：什么时候并发是负担

九、channel：通信，而不是共享内存

38. channel 的设计哲学

3. Go 项目结构与 `go mod` 的真实作用

10. `&` 和 `*` 的真实含义

30. `if err != nil` 为什么是设计选择