Flexport供应链集成参考架构

v20260423

flexport-reference-architecture

本指南提供了构建健壮且可扩展的Flexport供应链集成参考架构。它详细阐述了一个结构化的数据管道，包括Ingest（接收器）、Core（业务逻辑服务）和Expose（API/仪表盘）三个核心层，指导用户遵循最佳实践，实现可靠的数据流、缓存和消息队列机制。

Flexport 物流集成架构供应链 Webhook API 后端

获取技能

59 次下载

概览

Flexport Reference Architecture

Overview

Production reference architecture for Flexport logistics integrations. Three core services: Ingest (webhooks + polling), Core (business logic), and Expose (API + dashboard).

Architecture

┌──────────────────────────────────────────────────────┐
│                    Your Application                   │
├──────────────┬──────────────────┬─────────────────────┤
│  Ingest      │  Core            │  Expose             │
│              │                  │                     │
│  Webhook     │  Shipment        │  REST API           │
│  Receiver    │  Service         │  (your clients)     │
│              │                  │                     │
│  Scheduled   │  Product         │  Dashboard          │
│  Sync        │  Service         │  (Next.js/Astro)    │
│              │                  │                     │
│  Event       │  Invoice         │  Notifications      │
│  Queue       │  Service         │  (email/slack)      │
├──────────────┴──────────────────┴─────────────────────┤
│  Infrastructure: Cache (Redis) │ DB (Postgres) │ Queue │
├───────────────────────────────────────────────────────┤
│  Flexport API v2 (https://api.flexport.com)           │
└───────────────────────────────────────────────────────┘

Project Layout

flexport-integration/
├── src/
│   ├── flexport/
│   │   ├── client.ts           # Singleton API client
│   │   ├── types.ts            # Zod schemas for API responses
│   │   └── webhooks.ts         # Webhook signature + routing
│   ├── services/
│   │   ├── shipment.service.ts # Shipment CRUD + tracking
│   │   ├── product.service.ts  # Product catalog sync
│   │   ├── invoice.service.ts  # Commercial + freight invoices
│   │   └── booking.service.ts  # Booking creation + amendments
│   ├── jobs/
│   │   ├── sync-shipments.ts   # Scheduled full sync (hourly)
│   │   └── cache-warmup.ts     # Pre-populate caches on deploy
│   ├── api/
│   │   ├── routes.ts           # Express/Fastify routes
│   │   └── middleware.ts       # Auth, logging, error handling
│   └── config/
│       ├── flexport.ts         # API config per environment
│       └── cache.ts            # TTL settings per data type
├── tests/
│   ├── unit/                   # Mocked API tests
│   └── integration/            # Live API tests (CI only)
├── .env.example
└── docker-compose.yml          # Redis + Postgres for local dev

Data Flow

Flexport API ──webhook──> Ingest ──queue──> Core ──cache──> Expose
                                    │                │
                                    └── DB (Postgres) ┘

Ingest: Webhook receiver validates signatures, enqueues events
Core: Services process events, sync with Flexport API, update DB
Expose: API/dashboard reads from DB + cache, never directly from Flexport
Scheduled jobs: Hourly full sync catches any missed webhooks

Key Design Decisions

Decision	Choice	Rationale
Database	PostgreSQL	Structured logistics data, JSONB for flexible fields
Cache	Redis with 5min TTL	Shipment data changes infrequently
Queue	BullMQ	Retry, dead letter, rate limiting built in
API client	Custom fetch wrapper	No official SDK, typed with Zod
Webhook processing	Async via queue	Fast 200 response, process later

Resources

Next Steps

For multi-environment setup, see flexport-multi-env-setup.

信息

Category 编程开发

Name flexport-reference-architecture

版本 v20260423

大小 4.86KB

Source jeremylongshore/claude-code-plugins-plus-skills

更新时间 2026-04-28