PHPackages zhaiyuxin/japanpost - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. zhaiyuxin/japanpost ActiveLibrary[Utility & Helpers](/categories/utility) zhaiyuxin/japanpost =================== v1.0.0(10mo ago)452MITPHPCI passing Since Sep 2Pushed 2mo agoCompare [ Source](https://github.com/zhaiyuxin103/japanpost)[ Packagist](https://packagist.org/packages/zhaiyuxin/japanpost)[ GitHub Sponsors](https://github.com/zhaiyuxin103)[ RSS](/packages/zhaiyuxin-japanpost/feed)WikiDiscussions main Synced today READMEChangelog (1)Dependencies (6)Versions (2)Used By (0) JapanPost API Package ===================== [](#japanpost-api-package) [![Latest Version on Packagist](https://camo.githubusercontent.com/492a27d469a054d12573c05de2167561f03504ce4388e712d0c7fc5ce6092074/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7a686169797578696e2f6a6170616e706f73743f7374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/zhaiyuxin/japanpost)[![Total Downloads on Packagist](https://camo.githubusercontent.com/ca8e3c5eb217a36a54034a7c2fe61b5c026483221fb30df5019ec07cf9c37bda/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7a686169797578696e2f6a6170616e706f73743f7374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/zhaiyuxin/japanpost)[![Build Status](https://camo.githubusercontent.com/6c4916841b82b7f147d1c1f017e6f266170a915d7103bca1a11d91522c4f48bf/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f7a686169797578696e3130332f6a6170616e706f73742f74657374732e796d6c3f7374796c653d666f722d7468652d6261646765)](https://github.com/zhaiyuxin103/japanpost/actions)[![Code Coverage](https://camo.githubusercontent.com/c05649ef37e51701fc7c7518e86a7a8686e3e969ce6536a1477f34b005832504/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f7a686169797578696e3130332f6a6170616e706f73743f7374796c653d666f722d7468652d6261646765)](https://codecov.io/gh/zhaiyuxin103/japanpost)[![Laravel](https://camo.githubusercontent.com/d8a79c0ec60383c616905fb4433bdb6e96d0defb1189daa54a71f98b8f011098/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d31302e782d7265642e7376673f7374796c653d666f722d7468652d6261646765)](https://laravel.com)[![PHP](https://camo.githubusercontent.com/ff3b2fdf9638647aecf8e4823587e09fc89ff0aba804b7623df07e3128906ef3/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e332b2d626c75652e7376673f7374796c653d666f722d7468652d6261646765)](https://php.net)[![License](https://camo.githubusercontent.com/9897f4467850972a38c7db9a4d38280b8fcdac0ada00e9c8c0a72ecfa8551653/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666f722d7468652d6261646765)](LICENSE) 一个用于与日本邮政 API 交互的 PHP 包，提供地址查询、邮编搜索等功能。 ✨ 特性 ---- [](#-特性) - 🔐 **身份验证管理** - 自动处理 API 令牌获取和刷新 - 📍 **地址查询** - 根据各种条件搜索日本地址信息 - 🏷️ **邮编搜索** - 通过邮编代码查找对应的地址信息 - 🚀 **Laravel 集成** - 原生 Laravel 服务提供者支持 - 🎭 **Facade 支持** - 统一的 Facade 接口，简化调用 - 🛡️ **异常处理** - 完善的错误处理和自定义异常 - ⚙️ **灵活配置** - 支持自定义 HTTP 客户端选项 - 💾 **Token 缓存** - 自动缓存 API 令牌，提高性能 - 🌐 **多环境支持** - 支持测试和生产环境切换 - 🔌 **HTTP 抽象层** - 内置 HttpClient 封装，支持复用 📋 系统要求 ------ [](#-系统要求) - PHP >= 8.3 - Laravel >= 10.0 🚀 快速开始 ------ [](#-快速开始) ### 通过 Composer 安装 [](#通过-composer-安装) ``` composer require zhaiyuxin/japanpost ``` 🔧 配置 ---- [](#-配置) ### 环境变量 [](#环境变量) 在您的 `.env` 文件中添加以下配置： ``` JAPANPOST_CLIENT_ID=your_client_id_here JAPANPOST_SECRET_KEY=your_secret_key_here JAPANPOST_BASE_URI=https://api.da.pf.japanpost.jp/ ``` **环境配置说明：** - `JAPANPOST_BASE_URI`：API 基础 URL，支持测试和生产环境 - 生产环境：`https://api.da.pf.japanpost.jp/`（默认） - 测试环境：根据实际测试地址配置 ### 配置文件 [](#配置文件) 配置文件位于 `config/services.php`： ``` 'japanpost' => [ 'client_id' => env('JAPANPOST_CLIENT_ID'), 'secret_key' => env('JAPANPOST_SECRET_KEY'), 'base_uri' => env('JAPANPOST_BASE_URI', 'https://api.da.pf.japanpost.jp/'), ], ``` 📖 使用方法 ------ [](#-使用方法) ### 🎭 Laravel Facade 使用 [](#-laravel-facade-使用) 为了提供更简洁的 API，本包提供了一个统一的 Facade 接口。您可以通过 Facade 轻松访问所有服务： ``` use Yuxin\Japanpost\Facades\Japanpost; // 获取 Token 服务 $token = Japanpost::token()->getToken(); // 获取地址查询服务 $addresses = Japanpost::addressZip()->search([ 'prefecture' => '東京都', 'city' => '渋谷区', ]); // 获取邮编搜索服务 $addresses = Japanpost::searchCode()->search('150-0002'); ``` **Facade 优势：** - ✅ **统一接口**：一个 Facade 访问所有服务 - ✅ **简洁语法**：无需手动实例化或依赖注入 - ✅ **单例模式**：每次调用返回相同的实例 - ✅ **Laravel 集成**：完美融入 Laravel 生态系统 - ✅ **类型提示**：完整的 IDE 类型提示支持 ### 1. 获取 API 令牌 [](#1-获取-api-令牌) ``` use Yuxin\Japanpost\Token; use Psr\SimpleCache\CacheInterface; // 通过依赖注入获取（推荐，自动启用缓存） $token = app('japanpost.token')->getToken(); // 直接实例化（使用默认文件缓存） $tokenService = new Token($clientId, $secretKey, 'https://api.da.pf.japanpost.jp/'); $token = $tokenService->getToken(); // 自定义缓存实现 $tokenService = new Token($clientId, $secretKey, 'https://api.da.pf.japanpost.jp/', $cache); $token = $tokenService->getToken(); // 自定义 HTTP 客户端 use Yuxin\Japanpost\HttpClient; $httpClient = new HttpClient('https://api.da.pf.japanpost.jp/', ['timeout' => 30]); $tokenService = new Token($clientId, $secretKey, 'https://api.da.pf.japanpost.jp/', null, $httpClient); $token = $tokenService->getToken(); ``` **缓存机制：** - 自动缓存 API 令牌，默认缓存时间为 3600 秒（1小时） - 使用 PSR-16 缓存标准，支持多种缓存实现 - Laravel 环境中自动使用 Laravel 缓存系统 - 独立使用时默认使用 Symfony 文件缓存 ### 2. 地址查询 [](#2-地址查询) ``` use Yuxin\Japanpost\AddressZip; // 通过依赖注入获取 $addressService = app('japanpost.address_zip'); // 搜索地址（page 默认 1，limit 默认 1000） $addresses = $addressService->search([ 'prefecture' => '東京都', 'city' => '渋谷区', 'street' => '渋谷', ], 1, 100); // 直接实例化 $addressService = new AddressZip($clientId, $secretKey, 'https://api.da.pf.japanpost.jp/', $token); $addresses = $addressService->search([ 'prefecture' => '東京都', 'city' => '渋谷区', ]); ``` ### 3. 邮编搜索 [](#3-邮编搜索) ``` use Yuxin\Japanpost\SearchCode; // 通过依赖注入获取 $searchService = app('japanpost.search_code'); // 通过邮编搜索地址 // 参数：code, page=1, limit=1000, choikitype=1, searchtype=1 $addresses = $searchService->search('150-0002', 1, 100); // 直接实例化 $searchService = new SearchCode($clientId, $secretKey, 'https://api.da.pf.japanpost.jp/', $token); $addresses = $searchService->search('150-0002'); ``` **SearchCode 参数说明：** 参数类型默认值说明`$code`string-邮编代码`$page`int1页码`$limit`int1000每页条数`$choikitype`int1町域类型`$searchtype`int1搜索类型### 4. 自定义 HTTP 客户端 [](#4-自定义-http-客户端) 本包内置了 `HttpClient` 类，对 Guzzle HTTP 客户端进行了封装，支持客户端复用： ``` use Yuxin\Japanpost\HttpClient; // 创建自定义 HTTP 客户端 $httpClient = new HttpClient('https://api.da.pf.japanpost.jp/', [ 'timeout' => 30, 'verify' => false, 'headers' => [ 'User-Agent' => 'MyApp/1.0', ], ]); // 动态修改选项 $httpClient->setOptions(['timeout' => 60]); // 执行请求 $response = $httpClient->get('/api/v1/searchcode/150-0002'); $response = $httpClient->post('/api/v1/addresszip', ['json' => $data]); ``` 也可以通过各服务类的 `setGuzzleOptions()` 方法配置： ``` $addressService = app('japanpost.address_zip'); $addressService->setGuzzleOptions([ 'timeout' => 30, 'verify' => false, 'headers' => [ 'User-Agent' => 'MyApp/1.0', ], ]); ``` ### 5. 多环境配置示例 [](#5-多环境配置示例) ``` // 生产环境配置 $productionToken = new Token($clientId, $secretKey, 'https://api.da.pf.japanpost.jp/'); $productionAddress = new AddressZip($clientId, $secretKey, 'https://api.da.pf.japanpost.jp/', $token); $productionSearch = new SearchCode($clientId, $secretKey, 'https://api.da.pf.japanpost.jp/', $token); // 测试环境配置 $testBaseUri = 'https://test-api.example.com/'; $testToken = new Token($clientId, $secretKey, $testBaseUri); $testAddress = new AddressZip($clientId, $secretKey, $testBaseUri, $token); $testSearch = new SearchCode($clientId, $secretKey, $testBaseUri, $token); ``` 🐛 异常处理 ------ [](#-异常处理) 包提供了以下自定义异常： - `Yuxin\Japanpost\Exceptions\HttpException` - HTTP 请求异常 - `Yuxin\Japanpost\Exceptions\AddressesNotFoundException` - 地址未找到异常 - `Yuxin\Japanpost\Exceptions\Exception` - 通用异常 ``` use Yuxin\Japanpost\Exceptions\AddressesNotFoundException; use Yuxin\Japanpost\Exceptions\HttpException; try { $addresses = $addressService->search(['prefecture' => '東京都']); } catch (AddressesNotFoundException $e) { // 处理地址未找到的情况 Log::warning('No addresses found for Tokyo'); } catch (HttpException $e) { // 处理 HTTP 错误 Log::error('HTTP error: ' . $e->getMessage()); } ``` 🧪 测试 ---- [](#-测试) ### 运行测试套件 [](#运行测试套件) ``` composer test ``` ### 运行代码质量检查 [](#运行代码质量检查) ``` composer lint ``` ### 代码重构检查 [](#代码重构检查) ``` composer test:refactor # 预览 Rector 重构建议（dry-run） composer refactor # 执行 Rector 重构 ``` ### 测试框架 [](#测试框架) 本项目使用 **Pest PHP** 作为测试框架，配合 Orchestra Testbench 进行 Laravel 包测试。 #### 测试结构 [](#测试结构) ``` tests/ ├── Feature/ # 集成测试 │ ├── FacadeTest.php # Facade 功能测试 │ ├── IntegrationTest.php # 服务集成测试 │ └── ServiceProviderTest.php # 服务提供商测试 ├── Unit/ # 单元测试 │ ├── AddressZipTest.php # AddressZip 类测试 │ ├── ExceptionsTest.php # 异常处理测试 │ ├── HelpersTest.php # 辅助函数测试 │ ├── SearchCodeTest.php # SearchCode 类测试 │ └── TokenTest.php # Token 类测试 ├── Pest.php # Pest 配置文件 └── TestCase.php # 基础测试用例 ``` #### 测试特点 [](#测试特点) - **现代语法**: 使用 Pest 的 `test()` 和 `expect()` 函数 - **类型安全**: 所有测试都包含严格类型声明 - **完整覆盖**: 包含单元测试、集成测试和异常测试 - **Laravel 集成**: 使用 Orchestra Testbench 模拟 Laravel 环境 - **依赖注入**: 完整测试 Laravel 服务容器绑定 - **Facade 测试**: 专门测试 Facade 功能和服务访问 #### 编写测试示例 [](#编写测试示例) ``` // 单元测试 test('token can be instantiated with required parameters', function () { $token = new Token('test_client_id', 'test_secret_key', 'https://api.da.pf.japanpost.jp/'); expect($token)->toBeInstanceOf(Token::class); }); // 集成测试 test('services can be used with dependency injection', function () { $token = app('japanpost.token'); $addressZip = app('japanpost.address_zip'); $searchCode = app('japanpost.search_code'); expect($token)->toBeInstanceOf(Token::class); expect($addressZip)->toBeInstanceOf(AddressZip::class); expect($searchCode)->toBeInstanceOf(SearchCode::class); }); ``` ### 测试覆盖率 [](#测试覆盖率) 目前测试覆盖率达到 100%，包含： - ✅ 所有核心服务类的功能测试 - ✅ 异常处理和错误情况测试 - ✅ Laravel 服务提供商集成测试 - ✅ HTTP 客户端配置和选项测试 - ✅ 缓存机制测试 - ✅ Facade 功能和接口测试 - ✅ 辅助函数和工具类测试 🔧 开发 ---- [](#-开发) ### 构建工作台 [](#构建工作台) ``` composer build ``` ### 启动开发服务器 [](#启动开发服务器) ``` composer serve ``` 📦 依赖 ---- [](#-依赖) ### 运行时依赖 [](#运行时依赖) 包版本用途`guzzlehttp/guzzle`^7.10HTTP 客户端`psr/simple-cache`^3.0PSR-16 缓存接口`symfony/cache`^7.3默认缓存实现### 开发依赖 [](#开发依赖) 包版本用途`pestphp/pest`^4.0测试框架`mockery/mockery`^1.6Mock 库`laravel/pint`^1.24代码格式化`phpstan/phpstan`^2.1静态分析`orchestra/testbench`^10.6Laravel 包测试`rector/rector`^2.1代码重构🤝 贡献指南 ------ [](#-贡献指南) 欢迎提交 Issue 和 Pull Request！ 1. Fork 本项目 2. 创建特性分支 (`git checkout -b feature/xxx`) 3. 提交更改 (`git commit -m 'feat: add some xxx'`) 4. 推送到分支 (`git push origin feature/xxx`) 5. 开启 Pull Request 📄 许可证 ----- [](#-许可证) 本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。 📞 联系方式 ------ [](#-联系方式) - 项目主页: [GitHub Repository](https://github.com/zhaiyuxin103/japanpost) - 问题反馈: [Issues](https://github.com/zhaiyuxin103/japanpost/issues) - 技术讨论: [Discussions](https://github.com/zhaiyuxin103/japanpost/discussions) ### Health Score 33 — LowBetter than 72% of packages Maintenance71 Regular maintenance activity Popularity9 Limited adoption so far Community10 Small or concentrated contributor base Maturity36 Early-stage or recently created project Bus Factor1 Top contributor holds 66.7% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 306d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/30651809?v=4)[YuXin Zhai](/maintainers/zhaiyuxin103)[@zhaiyuxin103](https://github.com/zhaiyuxin103) --- Top Contributors [![zhaiyuxin103](https://avatars.githubusercontent.com/u/30651809?v=4)](https://github.com/zhaiyuxin103 "zhaiyuxin103 (2 commits)")[![actions-user](https://avatars.githubusercontent.com/u/65916846?v=4)](https://github.com/actions-user "actions-user (1 commits)") ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/zhaiyuxin-japanpost/health.svg) ``` [![Health](https://phpackages.com/badges/zhaiyuxin-japanpost/health.svg)](https://phpackages.com/packages/zhaiyuxin-japanpost) ``` ### Alternatives [aws/aws-sdk-php AWS SDK for PHP - Use Amazon Web Services in your PHP project 6.3k543.5M2.6k](/packages/aws-aws-sdk-php)[neuron-core/neuron-ai The PHP Agentic Framework. 2.0k656.1k38](/packages/neuron-core-neuron-ai)[tencentcloud/tencentcloud-sdk-php TencentCloudApi php sdk 3741.3M46](/packages/tencentcloud-tencentcloud-sdk-php)[civicrm/civicrm-core Open source constituent relationship management for non-profits, NGOs and advocacy organizations. 751291.4k43](/packages/civicrm-civicrm-core)[spatie/laravel-export Create a static site bundle from a Laravel app 674146.0k6](/packages/spatie-laravel-export)[oat-sa/tao-core TAO core extension 66143.7k124](/packages/oat-sa-tao-core) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)