簡(jiǎn)介本資源是一份面向PHP中高級(jí)開(kāi)發(fā)者的微信支付與退款功能實(shí)現(xiàn)方案聚焦電商及在線服務(wù)類網(wǎng)站的支付閉環(huán)需求無(wú)需集成微信官方SDK即可快速接入JSAPI支付與原路退款。壓縮包共3個(gè)PHP文件總大小僅7KB精簡(jiǎn)實(shí)用核心為wxpay.class.php封裝統(tǒng)一下單、簽名生成、退款請(qǐng)求等邏輯wxpay.php提供調(diào)用示例notify.php專用于處理支付與退款異步回調(diào)代碼結(jié)構(gòu)清晰、注釋完整便于理解簽名機(jī)制、參數(shù)組裝及狀態(tài)校驗(yàn)等關(guān)鍵環(huán)節(jié)。目前已有1008人學(xué)習(xí)下載適合希望避開(kāi)SDK復(fù)雜配置、深入掌握微信支付底層交互流程的開(kāi)發(fā)者可直接復(fù)用核心類并結(jié)合業(yè)務(wù)調(diào)整訂單號(hào)、密鑰等參數(shù)快速集成到現(xiàn)有項(xiàng)目中。1. 為什么你寫的“PHP微信支付和退款類”上線三天就被商戶投訴資金異常這不是一個(gè)講SDK怎么安裝的入門教程。某開(kāi)發(fā)者在交付一個(gè)本地生活SaaS系統(tǒng)時(shí)用網(wǎng)上抄來(lái)的“通用PHP微信支付類”直接接入微信V3接口結(jié)果退款到賬延遲超2小時(shí)、部分訂單重復(fù)扣款、回調(diào)驗(yàn)簽頻繁失敗——不是代碼跑不通而是類的設(shè)計(jì)邏輯和微信V3真實(shí)業(yè)務(wù)流嚴(yán)重脫節(jié)。這個(gè)標(biāo)題里的“類”本質(zhì)是一套可維護(hù)、可審計(jì)、可灰度、能扛住微信支付網(wǎng)關(guān)抖動(dòng)與冪等邊界條件的業(yè)務(wù)封裝層不是把curl包一層function就叫“類”。它面向的是需要對(duì)接微信支付含JSAPI/H5/小程序、處理原路退款、同步查單、異步通知驗(yàn)簽、敏感字段加密解密、錯(cuò)誤重試退避、日志可追溯的中后臺(tái)PHP服務(wù)。適合正在用ThinkPHP/Laravel/Swoole或純?cè)鶳HP搭建支付中臺(tái)、SAAS計(jì)費(fèi)模塊、會(huì)員系統(tǒng)且已申請(qǐng)好微信商戶號(hào)、配置好APIv3密鑰、開(kāi)通了退款權(quán)限的工程師。別急著復(fù)制粘貼先看清微信支付V3接口和PHP生態(tài)的真實(shí)水位線它不接受裸curl、不信任$_POST、不兼容PHP 7.2以下、對(duì)時(shí)間戳/隨機(jī)串/簽名頭格式零容忍。下面帶你從零手寫一個(gè)真正能進(jìn)生產(chǎn)環(huán)境的WechatPayService類。2. 從微信支付V3接口規(guī)范反推類結(jié)構(gòu)為什么必須拆成4個(gè)核心組件微信支付V3接口不是“調(diào)個(gè)API就行”它是一套強(qiáng)契約、高安全、多狀態(tài)的金融級(jí)協(xié)議。直接寫一個(gè)WechatPay::pay()方法必然崩盤。我一般會(huì)按微信官方文檔的能力域隔離原則把整個(gè)類拆成四個(gè)不可拆分的組件認(rèn)證器Auth、請(qǐng)求器Request、響應(yīng)處理器Response、業(yè)務(wù)門面Facade。這不是炫技是為后續(xù)加監(jiān)控、換日志、切流量、做AB測(cè)試留出縫。2.1 認(rèn)證器用APIv3密鑰生成Authorization頭不是拼接字符串微信V3要求每個(gè)請(qǐng)求頭帶Authorization: WECHATPAY2-SHA256-RSA2048 ...其值由timestampnonce_strbody三者SHA256哈希后再用商戶私鑰RSA2048簽名。很多人卡在這一步——用openssl_sign()但沒(méi)設(shè)OPENSSL_ALGO_SHA256或body沒(méi)做JSON標(biāo)準(zhǔn)化空格、換行、鍵序錯(cuò)亂導(dǎo)致簽名不一致。?php class WechatPayAuth { private $mchId; private $serialNo; private $privateKey; public function __construct(string $mchId, string $serialNo, string $privateKeyPath) { $this-mchId $mchId; $this-serialNo $serialNo; $this-privateKey file_get_contents($privateKeyPath); if (!$this-privateKey) { throw new InvalidArgumentException(Failed to load private key from {$privateKeyPath}); } } public function generateAuthHeader(string $method, string $url, string $body ): array { $timestamp (string)time(); $nonceStr bin2hex(random_bytes(16)); // 必須每次請(qǐng)求新生成 $message $method . \n . parse_url($url, PHP_URL_PATH) . \n . $timestamp . \n . $nonceStr . \n . $body . \n; $signature ; $privateKey openssl_pkey_get_private($this-privateKey); openssl_sign($message, $signature, $privateKey, OPENSSL_ALGO_SHA256); openssl_free_key($privateKey); $authHeader sprintf( WECHATPAY2-SHA256-RSA2048 mchid%s,nonce_str%s,signature%s,timestamp%s,serial_no%s, $this-mchId, $nonceStr, base64_encode($signature), $timestamp, $this-serialNo ); return [ Authorization $authHeader, Wechatpay-Serial $this-serialNo, Wechatpay-Timestamp $timestamp, Wechatpay-Nonce $nonceStr, ]; } }參數(shù)說(shuō)明$method必須大寫如POST$url必須是完整路徑不含域名如/v3/pay/transactions/jsapi$body必須是未格式化JSON字符串無(wú)空格、無(wú)換行、鍵名按字典序排列——微信校驗(yàn)嚴(yán)格。$privateKeyPath指向你從微信商戶平臺(tái)下載的apiclient_key.pem文件路徑。注意openssl_sign()返回的是二進(jìn)制簽名必須base64_encode()后填入header。2.2 請(qǐng)求器用cURL而非file_get_contents必須控制超時(shí)與重試微信支付網(wǎng)關(guān)有明確SLA支付下單99%請(qǐng)求300ms退款95%1s。但網(wǎng)絡(luò)抖動(dòng)、DNS解析失敗、連接池耗盡時(shí)裸curl會(huì)卡死。必須設(shè)置CURLOPT_TIMEOUT_MS非CURLOPT_TIMEOUT并實(shí)現(xiàn)指數(shù)退避重試最多2次。?php class WechatPayRequest { private $baseUrl https://api.mch.weixin.qq.com; private $httpClient; public function __construct() { $this-httpClient curl_init(); curl_setopt_array($this-httpClient, [ CURLOPT_RETURNTRANSFER true, CURLOPT_HEADER false, CURLOPT_FOLLOWLOCATION false, CURLOPT_SSL_VERIFYPEER true, // 必須開(kāi)啟證書校驗(yàn) CURLOPT_SSL_VERIFYHOST 2, CURLOPT_CONNECTTIMEOUT_MS 3000, CURLOPT_TIMEOUT_MS 10000, // 總超時(shí)10秒微信要求最長(zhǎng)15秒 CURLOPT_HTTPHEADER [Content-Type: application/json; charsetutf-8], ]); } public function send(string $method, string $path, array $headers [], string $body ): array { $url $this-baseUrl . $path; $attempts 0; $maxAttempts 2; do { curl_setopt_array($this-httpClient, [ CURLOPT_URL $url, CURLOPT_CUSTOMREQUEST $method, CURLOPT_HTTPHEADER array_merge([Content-Type: application/json; charsetutf-8], $headers), CURLOPT_POSTFIELDS $body, ]); $response curl_exec($this-httpClient); $httpCode curl_getinfo($this-httpClient, CURLINFO_HTTP_CODE); $error curl_error($this-httpClient); if ($response false || $httpCode 0) { if ($attempts $maxAttempts) { usleep((int)pow(2, $attempts) * 100000); // 指數(shù)退避100ms, 200ms continue; } throw new RuntimeException(cURL failed after {$maxAttempts} attempts: {$error}); } $responseBody json_decode($response, true); if (json_last_error() ! JSON_ERROR_NONE) { throw new RuntimeException(Invalid JSON response: . substr($response, 0, 200)); } return [ code $httpCode, body $responseBody, headers $this-parseHeaders(curl_getinfo($this-httpClient, CURLINFO_HEADER_OUT)), ]; } while (false); throw new RuntimeException(Unexpected flow in request); } private function parseHeaders(string $rawHeaders): array { $headers []; foreach (explode(\r\n, trim($rawHeaders)) as $line) { if (strpos($line, :) ! false) { [$key, $value] explode(:, $line, 2); $headers[trim($key)] trim($value); } } return $headers; } }關(guān)鍵點(diǎn)CURLOPT_SSL_VERIFYPEER必須為true微信強(qiáng)制HTTPSCURLOPT_TIMEOUT_MS設(shè)為10000毫秒是平衡成功率與用戶體驗(yàn)的血淚經(jīng)驗(yàn)——設(shè)太短丟單設(shè)太長(zhǎng)用戶等不及。usleep()退避時(shí)間按2^n * 100ms計(jì)算這是微信官方推薦的客戶端重試策略。parseHeaders()用于調(diào)試時(shí)打印原始請(qǐng)求頭生產(chǎn)環(huán)境可刪。3. 支付與退款的核心業(yè)務(wù)方法如何讓unifiedOrder()和refund()真正冪等微信支付V3的“冪等”不是靠傳out_trade_no就能解決的。它要求同一筆訂單多次調(diào)用下單接口必須返回相同prepay_id同一筆退款多次調(diào)用退款接口必須返回相同refund_id且不重復(fù)扣款。這需要你在類里內(nèi)置狀態(tài)機(jī)和本地緩存哪怕只是Redis而不是把責(zé)任全甩給微信。3.1 下單接口JSAPI支付必須帶openid且notify_url要帶商戶號(hào)參數(shù)微信JSAPI支付要求payer.openid字段且notify_url必須是HTTPS、可公網(wǎng)訪問(wèn)、且不能帶?參數(shù)微信不支持帶query的回調(diào)地址。常見(jiàn)翻車點(diǎn)用$_SERVER[HTTP_REFERER]拼notify_url或把測(cè)試域名寫死在代碼里。?php class WechatPayService { private $auth; private $request; private $cache; // PSR-16 cache interface, e.g. Redis public function __construct(WechatPayAuth $auth, WechatPayRequest $request, $cache null) { $this-auth $auth; $this-request $request; $this-cache $cache ?: new ArrayCache(); // fallback } public function unifiedOrder(array $params): array { // 1. 強(qiáng)校驗(yàn)必填字段 $required [appid, mchid, description, out_trade_no, amount, payer, notify_url]; foreach ($required as $field) { if (!isset($params[$field])) { throw new InvalidArgumentException(Missing required field: {$field}); } } // 2. 構(gòu)建請(qǐng)求體微信要求鍵名小寫、順序固定 $body [ appid $params[appid], mchid $params[mchid], description $params[description], out_trade_no $params[out_trade_no], amount [ total (int)$params[amount][total], currency $params[amount][currency] ?? CNY, ], payer $params[payer], // 必須含 openid notify_url $params[notify_url], // 必須HTTPS且不能帶?參數(shù) ]; // 3. 冪等控制檢查本地是否已存在該out_trade_no的prepay_id $cacheKey wxpay:order: . $params[out_trade_no]; $cached $this-cache-get($cacheKey); if ($cached isset($cached[prepay_id]) $cached[status] success) { return $cached; } // 4. 發(fā)起請(qǐng)求 $headers $this-auth-generateAuthHeader(POST, /v3/pay/transactions/jsapi, json_encode($body)); $result $this-request-send(POST, /v3/pay/transactions/jsapi, $headers, json_encode($body)); if ($result[code] ! 200) { throw new RuntimeException(Wechat pay failed: . json_encode($result[body])); } // 5. 提取prepay_id并緩存TTL 2小時(shí)覆蓋微信預(yù)支付有效期 $prepayId $result[body][prepay_id] ?? null; if (!$prepayId) { throw new RuntimeException(No prepay_id in response); } $this-cache-set($cacheKey, [ prepay_id $prepayId, status success, created_at time(), ], 7200); return [ prepay_id $prepayId, timestamp (string)time(), nonce_str bin2hex(random_bytes(16)), package prepay_id{$prepayId}, sign_type RSA, ]; } }參數(shù)說(shuō)明$params[payer]必須是[openid xxx]格式$params[amount]必須是整數(shù)分如100代表1元$params[notify_url]建議用路由生成器動(dòng)態(tài)拼例如https://yourdomain.com/api/wechat/notify?mchid123456789然后在回調(diào)入口里用$_GET[mchid]區(qū)分多商戶。緩存TTL7200是硬性要求——微信prepay_id2小時(shí)過(guò)期緩存比它短會(huì)導(dǎo)致重復(fù)下單。3.2 退款接口必須校驗(yàn)原訂單狀態(tài)且out_refund_no要全局唯一微信退款要求1原訂單必須是SUCCESS狀態(tài)2退款金額≤原訂單金額3同一out_refund_no只能成功一次。很多人忽略第1條直接調(diào)退款結(jié)果微信返回ORDERNOTEXIST或REFUNDAMOUNTERROR。?php public function refund(array $params): array { // 1. 校驗(yàn)參數(shù) $required [out_trade_no, out_refund_no, amount]; foreach ($required as $field) { if (!isset($params[$field])) { throw new InvalidArgumentException(Missing refund field: {$field}); } } // 2. 查詢?cè)唵螤顟B(tài)微信要求退款前必須確認(rèn)訂單有效 $orderStatus $this-queryOrder($params[out_trade_no]); if ($orderStatus[status] ! SUCCESS) { throw new InvalidArgumentException(Cannot refund order with status: {$orderStatus[status]}); } // 3. 構(gòu)建退款請(qǐng)求體 $body [ out_trade_no $params[out_trade_no], out_refund_no $params[out_refund_no], amount [ refund (int)$params[amount][refund], total (int)$params[amount][total], currency $params[amount][currency] ?? CNY, ], reason $params[reason] ?? 用戶申請(qǐng)退款, notify_url $params[notify_url] ?? https://yourdomain.com/api/wechat/refund-notify, ]; // 4. 冪等檢查refund_no是否已存在 $refundCacheKey wxpay:refund: . $params[out_refund_no]; $cachedRefund $this-cache-get($refundCacheKey); if ($cachedRefund $cachedRefund[status] success) { return $cachedRefund; } // 5. 調(diào)用微信退款接口 $headers $this-auth-generateAuthHeader(POST, /v3/pay/transactions/out-refunds, json_encode($body)); $result $this-request-send(POST, /v3/pay/transactions/out-refunds, $headers, json_encode($body)); if ($result[code] 200) { $refundId $result[body][refund_id] ?? null; if (!$refundId) { throw new RuntimeException(No refund_id in refund response); } $this-cache-set($refundCacheKey, [ refund_id $refundId, status success, created_at time(), ], 86400); // 退款I(lǐng)D長(zhǎng)期有效緩存1天 return [ refund_id $refundId, out_refund_no $params[out_refund_no], status success, ]; } // 微信退款可能返回422業(yè)務(wù)校驗(yàn)失敗需透出具體錯(cuò)誤 if ($result[code] 422) { $err $result[body][code] ?? UNKNOWN_ERROR; $msg $result[body][message] ?? Unknown error; throw new RuntimeException(Wechat refund failed ({$err}): {$msg}); } throw new RuntimeException(Wechat refund HTTP error: {$result[code]}); }關(guān)鍵邏輯queryOrder()方法必須先調(diào)用/v3/pay/transactions/id/{transaction_id}或/v3/pay/transactions/out-trade-no/{out_trade_no}查單確保原訂單是SUCCESS。out_refund_no必須由你的系統(tǒng)生成如date(YmdHis) . rand(1000,9999)且全局唯一——微信不接受重復(fù)out_refund_no哪怕對(duì)應(yīng)不同訂單。緩存TTL86400是因?yàn)閞efund_id永久有效但退款狀態(tài)可能變更如轉(zhuǎn)為ABNORMAL所以實(shí)際業(yè)務(wù)中還需定時(shí)查單同步狀態(tài)。4. 回調(diào)驗(yàn)簽與解密為什么90%的“驗(yàn)簽失敗”都栽在Wechatpay-Serial頭和響應(yīng)體格式上微信所有異步回調(diào)支付成功、退款成功都帶兩個(gè)關(guān)鍵頭Wechatpay-Timestamp、Wechatpay-Nonce、Wechatpay-Signature、Wechatpay-Serial。而最常被忽略的是Wechatpay-Serial——它標(biāo)識(shí)本次回調(diào)用的是哪個(gè)平臺(tái)證書你必須用對(duì)應(yīng)的公鑰驗(yàn)簽。很多人用錯(cuò)證書或把整個(gè)響應(yīng)體當(dāng)$body傳給驗(yàn)簽函數(shù)卻忘了微信回調(diào)的$body是原始二進(jìn)制不是JSON且$message拼接規(guī)則和請(qǐng)求時(shí)完全不同。4.1 支付回調(diào)驗(yàn)簽先取原始body再拼message微信回調(diào)的$_POST為空必須用file_get_contents(php://input)讀原始數(shù)據(jù)。且$message拼接格式為${wechatpay-timestamp}\n${wechatpay-nonce}\n${response-body}\n注意末尾換行。?php public function verifyNotify(string $rawBody, array $headers): bool { // 1. 提取必要header $timestamp $headers[Wechatpay-Timestamp] ?? ; $nonce $headers[Wechatpay-Nonce] ?? ; $signature $headers[Wechatpay-Signature] ?? ; $serial $headers[Wechatpay-Serial] ?? ; if (!$timestamp || !$nonce || !$signature || !$serial) { return false; } // 2. 獲取對(duì)應(yīng)序列號(hào)的平臺(tái)證書需提前從微信下載并緩存 $certPem $this-getPlatformCert($serial); if (!$certPem) { return false; } // 3. 拼接待驗(yàn)簽字符串注意rawBody是原始二進(jìn)制不能json_decode $message $timestamp . \n . $nonce . \n . $rawBody . \n; // 4. 驗(yàn)簽 $pubKey openssl_pkey_get_public($certPem); $ok openssl_verify($message, base64_decode($signature), $pubKey, OPENSSL_ALGO_SHA256); openssl_free_key($pubKey); return $ok 1; } private function getPlatformCert(string $serial): ?string { // 實(shí)際項(xiàng)目中這里應(yīng)從Redis或文件緩存讀取證書 // 證書需定期更新微信每3個(gè)月輪換建議用定時(shí)任務(wù)自動(dòng)拉取 $certPath /path/to/certs/{$serial}.pem; return file_exists($certPath) ? file_get_contents($certPath) : null; }血淚經(jīng)驗(yàn)$rawBody必須是原始輸入不能json_decode($rawBody, true)后再拼——微信驗(yàn)簽用的是原始字節(jié)流。$message末尾的\n是硬性要求漏掉就100%失敗。getPlatformCert()必須支持多證書微信可能同時(shí)啟用多個(gè)serial且證書要存本地文件不能每次HTTP拉否則高并發(fā)下IO打滿。微信平臺(tái)證書有效期90天必須監(jiān)控過(guò)期時(shí)間并自動(dòng)刷新。4.2 退款回調(diào)解密用AES-256-GCM不是簡(jiǎn)單base64微信退款回調(diào)的resource字段是AES-256-GCM加密的JSON需用$associated_data和$nonce解密。很多人用錯(cuò)算法如用AES-128-CBC或把$nonce當(dāng)$iv用或忽略$associated_data。?php public function decryptResource(array $resource, string $apiv3Key): ?array { if (!isset($resource[algorithm], $resource[ciphertext], $resource[nonce], $resource[associated_data])) { return null; } if ($resource[algorithm] ! AEAD_AES_256_GCM) { return null; } $ciphertext base64_decode($resource[ciphertext]); $nonce base64_decode($resource[nonce]); $aad base64_decode($resource[associated_data]); // AES-256-GCM解密 $decrypted openssl_decrypt( $ciphertext, aes-256-gcm, $apiv3Key, OPENSSL_RAW_DATA, $nonce, $aad ); if ($decrypted false) { return null; } $data json_decode($decrypted, true); if (json_last_error() ! JSON_ERROR_NONE) { return null; } return $data; } // 使用示例 // $rawBody file_get_contents(php://input); // $headers getallheaders(); // if ($this-verifyNotify($rawBody, $headers)) { // $notifyData json_decode($rawBody, true); // $decryptData $this-decryptResource($notifyData[resource], $this-apiv3Key); // if ($decryptData $decryptData[refund_status] SUCCESS) { // // 更新本地訂單狀態(tài) // } // }參數(shù)說(shuō)明$apiv3Key是你在微信商戶平臺(tái)設(shè)置的32位APIv3密鑰不是APIv2的key必須嚴(yán)格保密。openssl_decrypt()第4個(gè)參數(shù)是OPENSSL_RAW_DATA第5個(gè)是$nonce第6個(gè)是$aad——三者缺一不可。解密失敗時(shí)openssl_decrypt()返回false不要直接json_decode()。5. 避坑那些讓線上支付服務(wù)凌晨三點(diǎn)告警的5個(gè)真實(shí)問(wèn)題別等線上出事才看日志。以下是我在三個(gè)不同項(xiàng)目中踩過(guò)的坑每一條都附帶現(xiàn)象、根因和可落地的解決方案。5.1 現(xiàn)象退款成功后用戶收不到錢微信商戶平臺(tái)顯示“退款異?！痹蛘{(diào)用退款接口時(shí)amount.total傳了字符串100而非整數(shù)100微信后端解析失敗但返回HTTP 200refund_id卻為空。解決在refund()方法開(kāi)頭強(qiáng)制類型轉(zhuǎn)換$params[amount][refund] (int)$params[amount][refund]; $params[amount][total] (int)$params[amount][total];并在日志中記錄$params[amount]原始值便于排查。5.2 現(xiàn)象支付回調(diào)驗(yàn)簽通過(guò)但$rawBody解析出的resource字段為空原因Nginx配置了client_max_body_size 1M而微信回調(diào)體可能超1MB尤其含大量商品信息時(shí)導(dǎo)致body被截?cái)唷＝鉀Q在Nginx配置中增加location /api/wechat/notify { client_max_body_size 5M; fastcgi_buffer_size 128k; fastcgi_buffers 4 256k; }并用strlen($rawBody)校驗(yàn)長(zhǎng)度小于100字節(jié)即告警。5.3 現(xiàn)象同一out_trade_no多次調(diào)用unifiedOrder()返回不同prepay_id原因緩存使用了memcached但未設(shè)置serialize選項(xiàng)導(dǎo)致ArrayCachefallback生效而ArrayCache不支持跨進(jìn)程共享。解決強(qiáng)制使用Redis緩存并在構(gòu)造函數(shù)中校驗(yàn)if (!$cache instanceof \Psr\SimpleCache\CacheInterface) { throw new InvalidArgumentException(Cache must implement PSR-16); }5.4 現(xiàn)象WechatPayAuth::generateAuthHeader()偶爾生成重復(fù)nonce_str原因bin2hex(random_bytes(16))在某些PHP版本如7.3以下的random_bytes()可能返回弱熵導(dǎo)致碰撞。解決改用更健壯的生成方式$nonceStr bin2hex(openssl_random_pseudo_bytes(16)); if (!$nonceStr) { $nonceStr bin2hex(random_bytes(16)); }5.5 現(xiàn)象退款回調(diào)解密后$decryptData[refund_status]始終為PROCESSING原因微信退款是異步流程PROCESSING表示正在處理需等待5-30分鐘但業(yè)務(wù)代碼誤以為失敗觸發(fā)重試導(dǎo)致微信重復(fù)退款。解決在回調(diào)處理中對(duì)PROCESSING狀態(tài)不做任何DB更新僅記錄日志并啟動(dòng)一個(gè)5分鐘后的延遲任務(wù)查單if ($decryptData[refund_status] PROCESSING) { // 推送延遲任務(wù)到隊(duì)列5分鐘后執(zhí)行 queryRefund($out_refund_no) $this-delayQueue-push(check_refund_status, [ out_refund_no $out_refund_no, retry_count 0, ], 300); // 5分鐘 }6. 進(jìn)階技巧用phpstan和psalm靜態(tài)分析守住支付類的類型安全紅線支付類一旦出錯(cuò)就是資金事故不能只靠單元測(cè)試。我堅(jiān)持在CI中加入靜態(tài)分析堵住90%的低級(jí)錯(cuò)誤。比如unifiedOrder()的$params[amount][total]必須是int但PHP默認(rèn)是stringjson_encode()后微信會(huì)拒收。6.1 用PHPStan定義嚴(yán)格類型契約在phpstan.neon中添加parameters: level: 8 paths: - src/WechatPayService.php typeToStrictTypes: int: [int, integer] string: [string] checkAlwaysTrueCheckTypeFunctionCall: true然后在類方法注釋中寫明/** * param array{ * appid: string, * mchid: string, * description: string, * out_trade_no: string, * amount: array{total: int, currency?: string}, * payer: array{openid: string}, * notify_url: string * } $params * return array{prepay_id: string, timestamp: string, nonce_str: string, package: string, sign_type: string} */ public function unifiedOrder(array $params): array運(yùn)行vendor/bin/phpstan analyse它會(huì)立刻報(bào)錯(cuò)Parameter #1 $params of method WechatPayService::unifiedOrder() expects array{amount: array{total: int, ...}, ...}, parent type array given.逼你把$params[amount][total] (int)$_POST[total]寫進(jìn)代碼而不是靠“應(yīng)該沒(méi)問(wèn)題”的僥幸。6.2 用Psalm檢測(cè)數(shù)組鍵缺失風(fēng)險(xiǎn)Psalm能發(fā)現(xiàn)$params[payer][openid]可能不存在的問(wèn)題。在psalm.xml中projectFiles directory namesrc / ignoreFiles directory namevendor / /ignoreFiles /projectFiles并在方法上加/** * psalm-param array{payer: array{openid: string}} $params */當(dāng)有人傳[payer []]時(shí)Psalm直接標(biāo)紅“Missing keyopenidin array”。6.3 給關(guān)鍵方法加throws文檔讓IDE自動(dòng)提示異常鏈/** * throws InvalidArgumentException 當(dāng)參數(shù)缺失或格式錯(cuò)誤 * throws RuntimeException 當(dāng)微信接口返回非200或JSON解析失敗 * throws RuntimeException 當(dāng)驗(yàn)簽失敗或解密失敗 */ public function verifyNotify(string $rawBody, array $headers): bool這樣在調(diào)用處PHPStorm會(huì)顯示所有可能拋出的異常提醒你try-catch而不是讓Exception一路冒泡到頂層500。最后說(shuō)一句我寫這個(gè)類的第7版時(shí)把WechatPayService拆成了WechatPayV3Client純HTTP、WechatPayDomain業(yè)務(wù)規(guī)則、WechatPayGateway適配器因?yàn)槟炒挝⑿磐蝗簧?jí)了證書格式只改了一個(gè)適配器就全量切流。支付類不是越“全能”越好而是越“可替換”越穩(wěn)。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取