技术实战：海外版跑腿配送平台核心代码实现

在全球数字化浪潮下，同城跑腿服务正迅速向海外市场扩张。与国内环境不同，海外搭建需要应对更多技术挑战。本文将深入技术细节，通过实际代码示例，展示如何构建一个符合海外要求的跑腿配送平台。

一、海外特色技术架构设计

混合云部署架构：

用户层：iOS/Android/Web三端覆盖
接入层：CloudFront/Akamai CDN全球加速
应用层：AWS ECS/Fargate容器化部署（多区域）
服务层：
- 订单服务（Order Service）
- 调度服务（Dispatch Service）
- 支付服务（Payment Service）
- 通知服务（Notification Service）
数据层：Aurora PostgreSQL（主）+ DynamoDB（日志）+ Elasticache Redis
集成层：Google Maps API、Stripe/PayPal、Twilio

技术栈选择考量：

前端：React Native + TypeScript（跨平台且类型安全）
后端：Node.js + NestJS（快速迭代，生态丰富）
数据库：PostgreSQL + PostGIS（地理位置查询优化）
实时通信：Socket.io + Redis Adapter

二、核心模块代码实现

代码示例1：基于距离的动态定价服务

// src/pricing/dynamic-pricing.service.ts
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { HttpService } from '@nestjs/axios';

@Injectable()
export class DynamicPricingService {
constructor(
private configService: ConfigService,
private httpService: HttpService,
) {}

/**
* 计算动态配送价格
* @param baseDistance 基础距离（公里）
* @param basePrice 基础价格
* @param coordinates 起点和终点坐标
* @param demandFactor 需求系数
*/
async calculateDeliveryPrice(
baseDistance: number,
basePrice: number,
coordinates: {
pickup: { lat: number; lng: number };
dropoff: { lat: number; lng: number };
},
demandFactor: number = 1.0,
): Promise<{
distance: number;
duration: number;
price: number;
breakdown: any;
}> {
// 1. 获取实际距离和时间（使用Google Maps API）
const routeInfo = await this.getRouteInfo(
coordinates.pickup,
coordinates.dropoff,
);

// 2. 计算距离费用
const distancePrice = this.calculateDistancePrice(
routeInfo.distance,
baseDistance,
basePrice,
);

// 3. 计算时间系数（高峰时段加成）
const timeFactor = this.getTimeFactor();

// 4. 天气影响系数
const weatherFactor = await this.getWeatherFactor(coordinates.pickup);

// 5. 最终价格计算
const finalPrice = Math.max(
basePrice,
distancePrice * timeFactor * weatherFactor * demandFactor,
);

// 6. 货币格式化（支持多国货币）
const formattedPrice = this.formatCurrency(
finalPrice,
this.configService.get('LOCAL_CURRENCY'),
);

return {
distance: routeInfo.distance,
duration: routeInfo.duration,
price: finalPrice,
breakdown: {
basePrice,
distancePrice,
timeFactor,
weatherFactor,
demandFactor,
currency: formattedPrice,
},
};
}

private async getRouteInfo(origin: any, destination: any) {
const apiKey = this.configService.get('GOOGLE_MAPS_API_KEY');
const response = await this.httpService
.get('https://maps.googleapis.com/maps/api/directions/json', {
params: {
origin: `${origin.lat},${origin.lng}`,
destination: `${destination.lat},${destination.lng}`,
key: apiKey,
mode: 'driving',
alternatives: false,
},
})
.toPromise();

if (response.data.routes.length === 0) {
throw new Error('No route found');
}

const route = response.data.routes[0];
return {
distance: route.legs[0].distance.value / 1000, // 转换为公里
duration: route.legs[0].duration.value / 60, // 转换为分钟
};
}

private calculateDistancePrice(
actualDistance: number,
baseDistance: number,
basePrice: number,
): number {
if (actualDistance <= baseDistance) {
return basePrice;
}

const extraDistance = actualDistance - baseDistance;
const extraPrice = extraDistance * this.configService.get('PRICE_PER_KM');

return basePrice + extraPrice;
}

private getTimeFactor(): number {
const now = new Date();
const hour = now.getHours();

// 高峰时段价格加成
if ((hour >= 7 && hour <= 9) || (hour >= 17 && hour <= 19)) {
return 1.5; // 高峰时段加价50%
} else if (hour >= 22 || hour <= 6) {
return 2.0; // 夜间加价100%
}

return 1.0;
}

private async getWeatherFactor(location: any): Promise<number> {
// 集成天气API，恶劣天气加价
try {
const weather = await this.getWeatherData(location);
if (weather.condition === 'rain' || weather.condition === 'snow') {
return 1.3; // 雨雪天气加价30%
}
} catch (error) {
console.error('Failed to get weather data:', error);
}

return 1.0;
}

private formatCurrency(amount: number, currency: string): string {
const formatter = new Intl.NumberFormat(this.getLocale(currency), {
style: 'currency',
currency: currency,
minimumFractionDigits: 2,
});

return formatter.format(amount);
}

private getLocale(currency: string): string {
const localeMap = {
USD: 'en-US',
EUR: 'de-DE',
GBP: 'en-GB',
JPY: 'ja-JP',
CAD: 'en-CA',
AUD: 'en-AU',
};

return localeMap[currency] || 'en-US';
}
}

代码示例2：多语言订单状态通知服务

// src/notification/multilingual-notification.service.ts
import { Injectable } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import * as twilio from 'twilio';

interface OrderStatusNotification {
orderId: string;
userId: string;
userLanguage: string;
status: 'pending' | 'accepted' | 'picked_up' | 'delivered' | 'cancelled';
riderName?: string;
estimatedTime?: number;
}

@Injectable()
export class MultilingualNotificationService {
private twilioClient: twilio.Twilio;
private supportedLanguages = ['en', 'es', 'fr', 'zh', 'ja', 'ko'];

constructor(private configService: ConfigService) {
this.twilioClient = twilio(
configService.get('TWILIO_ACCOUNT_SID'),
configService.get('TWILIO_AUTH_TOKEN'),
);
}

/**
* 发送多语言订单状态通知
*/
async sendOrderStatusNotification(
notification: OrderStatusNotification,
): Promise<void> {
// 1. 获取用户偏好语言
const language = this.validateLanguage(notification.userLanguage);

// 2. 获取本地化消息模板
const message = this.getLocalizedMessage(language, notification);

// 3. 获取用户联系方式
const userContact = await this.getUserContact(notification.userId);

// 4. 多通道发送（SMS + Push Notification + Email）
await this.sendMultichannelNotification(userContact, message, language);

// 5. 记录通知日志
await this.logNotification(notification, message);
}

private validateLanguage(language: string): string {
return this.supportedLanguages.includes(language) ? language : 'en';
}

private getLocalizedMessage(
language: string,
notification: OrderStatusNotification,
): { sms: string; push: string; email: SubjectAndBody } {
const templates = {
en: {
pending: {
sms: `Your order #${notification.orderId} has been received and is being processed.`,
push: `Order confirmed! We're finding a rider for your delivery.`,
email: {
subject: 'Order Confirmed',
body: `Thank you for your order. We're preparing it for delivery.`,
},
},
accepted: {
sms: `Rider ${notification.riderName} has accepted your order #${notification.orderId}.`,
push: `Rider ${notification.riderName} is on the way to pick up your order.`,
email: {
subject: 'Rider Assigned',
body: `Your rider ${notification.riderName} will arrive shortly.`,
},
},
// ... 其他状态
},
es: {
pending: {
sms: `Su pedido #${notification.orderId} ha sido recibido y se está procesando.`,
push: `¡Pedido confirmado! Estamos buscando un repartidor.`,
email: {
subject: 'Pedido Confirmado',
body: `Gracias por su pedido. Lo estamos preparando para la entrega.`,
},
},
// ... 其他语言版本
},
zh: {
pending: {
sms: `您的订单 #${notification.orderId} 已接收，正在处理中。`,
push: `订单已确认！我们正在为您匹配骑手。`,
email: {
subject: '订单确认通知',
body: `感谢您的下单，我们正在准备配送。`,
},
},
// ... 其他语言版本
},
};

return templates[language][notification.status];
}

private async sendMultichannelNotification(
userContact: any,
message: any,
language: string,
): Promise<void> {
// 发送SMS（使用Twilio）
if (userContact.phone) {
await this.sendSMS(userContact.phone, message.sms, language);
}

// 发送推送通知（Firebase Cloud Messaging）
if (userContact.fcmToken) {
await this.sendPushNotification(userContact.fcmToken, message.push);
}

// 发送邮件
if (userContact.email) {
await this.sendEmail(
userContact.email,
message.email.subject,
this.buildEmailTemplate(message.email.body, language),
);
}
}

private async sendSMS(
phoneNumber: string,
message: string,
language: string,
): Promise<void> {
try {
await this.twilioClient.messages.create({
body: message,
from: this.configService.get('TWILIO_PHONE_NUMBER'),
to: this.formatPhoneNumber(phoneNumber, language),
statusCallback: `${this.configService.get('API_BASE_URL')}/sms/callback`,
});
} catch (error) {
console.error('Failed to send SMS:', error);
// 失败后尝试其他通道或重试逻辑
}
}

private formatPhoneNumber(phone: string, language: string): string {
// 国际电话格式化逻辑
const countryCodes = {
en: '+1', // 美国
es: '+34', // 西班牙
zh: '+86', // 中国
// ... 其他国家代码
};

const countryCode = countryCodes[language] || '+1';
return `${countryCode}${phone.replace(/\D/g, '')}`;
}

private async sendPushNotification(
fcmToken: string,
message: string,
): Promise<void> {
// 使用Firebase Admin SDK发送推送通知
const admin = require('firebase-admin');

if (!admin.apps.length) {
admin.initializeApp({
credential: admin.credential.cert(
this.configService.get('FIREBASE_SERVICE_ACCOUNT'),
),
});
}

const payload = {
notification: {
title: 'Order Update',
body: message,
sound: 'default',
},
data: {
type: 'order_update',
timestamp: new Date().toISOString(),
},
token: fcmToken,
};

try {
await admin.messaging().send(payload);
} catch (error) {
console.error('Failed to send push notification:', error);
}
}

private async sendEmail(
email: string,
subject: string,
htmlBody: string,
): Promise<void> {
// 使用AWS SES或SendGrid发送邮件
const sgMail = require('@sendgrid/mail');
sgMail.setApiKey(this.configService.get('SENDGRID_API_KEY'));

const msg = {
to: email,
from: this.configService.get('EMAIL_FROM'),
subject: subject,
html: htmlBody,
trackingSettings: {
clickTracking: { enable: true },
openTracking: { enable: true },
},
};

try {
await sgMail.send(msg);
} catch (error) {
console.error('Failed to send email:', error);
}
}

private buildEmailTemplate(body: string, language: string): string {
// 构建本地化邮件模板
return `
<!DOCTYPE html>
<html lang="${language}">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Order Notification</title>
<style>
body { font-family: Arial, sans-serif; direction: ${this.getTextDirection(language)}; }
.container { max-width: 600px; margin: 0 auto; padding: 20px; }
.header { background-color: #4CAF50; color: white; padding: 10px; text-align: center; }
.content { padding: 20px; }
.footer { text-align: center; font-size: 12px; color: #666; }
</style>
</head>
<body>
<div class="container">
<div class="header">
<h1>${this.getLocalizedHeader(language)}</h1>
</div>
<div class="content">
<p>${body}</p>
<p>${this.getLocalizedFooter(language)}</p>
</div>
<div class="footer">
<p>© ${new Date().getFullYear()} Delivery Platform. ${this.getLocalizedRights(language)}</p>
</div>
</div>
</body>
</html>

三、海外部署最佳实践

1. 多区域数据库策略

# database-config.yaml
regions:
- name: us-east-1
primary: true
databases:
orders: us-east-1-rds-cluster
users: global-dynamodb-table
- name: eu-west-1
primary: false
databases:
orders: eu-west-1-rds-read-replica
users: global-dynamodb-table
- name: ap-southeast-1
primary: false
databases:
orders: ap-southeast-1-rds-read-replica
users: global-dynamodb-table

sync:
orders_cross_region_replication: enabled
max_replication_lag: 300 # 5分钟

2. 合规性中间件实现

// GDPR合规中间件示例
@Injectable()
export class GdprComplianceMiddleware implements NestMiddleware {
use(req: Request, res: Response, next: NextFunction) {
// 记录数据处理活动
this.logDataProcessing(req);

// 检查用户同意状态
if (this.requiresConsent(req) && !this.hasConsent(req)) {
throw new ConsentRequiredException();
}

// 匿名化处理
if (this.shouldAnonymize(req)) {
req.body = this.anonymizeData(req.body);
}

// 设置数据保留头部
res.setHeader('X-Data-Retention-Period', '30 days');

next();
}
}

四、性能优化策略

地理位置查询优化：

-- 使用PostGIS高效查询附近骑手
CREATE INDEX idx_riders_location ON riders USING GIST(location);

SELECT
rider_id,
ST_Distance(
location,
ST_SetSRID(ST_MakePoint(:pickup_lng, :pickup_lat), 4326)
) as distance_meters
FROM riders
WHERE ST_DWithin(
location,
ST_SetSRID(ST_MakePoint(:pickup_lng, :pickup_lat), 4326),
:search_radius -- 搜索半径（米）
)
AND status = 'available'
ORDER BY distance_meters ASC
LIMIT 20;

五、监控与故障处理

分布式追踪配置：

// OpenTelemetry初始化
const { NodeTracerProvider } = require('@opentelemetry/node');
const { SimpleSpanProcessor } = require('@opentelemetry/tracing');
const { JaegerExporter } = require('@opentelemetry/exporter-jaeger');

const provider = new NodeTracerProvider();
provider.register();

const exporter = new JaegerExporter({
serviceName: 'delivery-api',
host: 'jaeger-agent',
});

provider.addSpanProcessor(new SimpleSpanProcessor(exporter));