概述
好停提供Java、Python、Node.js三种主流语言的SDK和集成示例，帮助您快速将停车管理能力集成到您的应用中。所有SDK均已开源，托管在GitHub上，您可以直接使用或根据需要进行定制。SDK封装了认证、请求签名、错误处理、Token自动刷新等通用逻辑，让您专注于业务开发。
Java示例（Spring Boot集成）
环境要求：JDK 1.8及以上、Maven 3.6及以上或Gradle 6.x。第一步，在pom.xml中添加好停SDK依赖（Maven Central可获取）。第二步，在application.yml中配置parkinglink.api.base-url、parkinglink.api.client-id、parkinglink.api.client-secret。第三步，创建ParkingLinkClient配置类（@Configuration），使用@Bean注解将ParkingLinkClient注入Spring容器，客户端会自动管理Access Token的获取和刷新。
第四步，在Service层编写业务代码。停车场查询示例：注入ParkingLinkClient后调用client.parkingLots().list(city, keyword, page, size)方法获取分页的停车场列表。创建订单示例：构建CreateOrderRequest对象（使用Builder模式），设置parkingLotId、plateNumber、vehicleType，调用client.orders().create(request)方法创建订单并获取orderId。发起支付示例：构建PayRequest对象，设置orderId、paymentMethod、amount，调用client.payments().pay(request)方法发起支付，返回支付URL或二维码。
第五步，处理Webhook回调。创建WebhookController，使用@PostMapping注解接收POST请求，通过请求头X-ParkingLink-Signature和X-ParkingLink-Timestamp实现签名验证。使用client.webhooks().verify(requestBody, signature, timestamp)方法验证签名合法性。验证通过后根据eventType分发到不同的业务处理方法。
Python示例（requests库）
环境要求：Python 3.7及以上。第一步，安装依赖：pip install parkinglink-sdk（或pip install requests用于手动集成）。第二步，创建ParkingLinkAPI类封装API调用逻辑，类中包含__init__方法初始化client_id、client_secret和base_url，get_access_token方法实现Token获取和缓存，以及各种业务方法的封装。
停车场查询示例：调用api.parking_lots.list(city='beijing', page=1, size=20)方法，传入参数获取停车场列表，返回dict格式数据。创建订单示例：调用api.orders.create(parking_lot_id='xxx', plate_number='京A12345', vehicle_type='car')方法创建订单并返回order_id。发起支付示例：调用api.payments.pay(order_id='xxx', payment_method='wechat', amount=500)方法发起支付。完整的异常处理和重试机制：封装了Token自动刷新、网络超时重试（使用tenacity库）、错误码处理等逻辑。建议在生产环境中使用连接池（requests.Session）和异步调用（asyncio + aiohttp）以提高性能。
Node.js示例（axios库）
环境要求：Node.js 14及以上。第一步，安装依赖：npm install parkinglink-sdk（或npm install axios用于手动集成）。第二步，创建parkinglink-client.js模块。使用axios.create创建HTTP客户端实例，配置baseURL、timeout、headers等。通过请求拦截器自动添加Authorization头，通过响应拦截器处理401错误自动刷新Token并重试请求。
停车场查询示例：调用client.parkingLots.list({city: 'beijing', page: 1, size: 20})方法，使用async/await语法获取停车场列表。创建订单示例：调用client.orders.create({parkingLotId: 'xxx', plateNumber: '京A12345', vehicleType: 'car'})方法创建停车订单。发起支付示例：调用client.payments.pay({orderId: 'xxx', paymentMethod: 'wechat', amount: 500})方法发起支付请求。
Express.js集成示例：创建完整的Express路由文件，实现GET /api/parking-lots（停车场查询）、POST /api/orders（订单创建）、POST /api/payments（支付发起）、POST /api/webhooks/parkinglink（Webhook接收）等功能。包含完整的错误处理中间件（统一异常捕获和响应格式）和请求日志记录（使用morgan或winston）。
通用最佳实践
Token管理：建议缓存access_token并在过期前5分钟自动刷新，避免在请求高峰时Token过期导致调用失败。使用单例模式管理Token，确保多线程/多进程环境下的Token一致性。错误处理：建议对所有API调用实施重试机制，对于网络超时和服务端5xx错误进行指数退避重试。对于4xx客户端错误（除401认证错误外），不应重试，应直接上报并修复参数问题。日志记录：建议记录每次API调用的请求参数、响应结果、耗时和错误信息，便于问题排查和性能分析。建议使用结构化日志格式（JSON），方便后续对接日志分析平台。速率限制：好停API对每个应用有速率限制（默认1000次/分钟），请在代码中实现请求速率控制，避免触发限流。可以通过响应头X-RateLimit-Remaining和X-RateLimit-Reset获取当前限流状态，动态调整请求频率。