fengling-activity/docs/NAMING_CONVENTION.md

Service Naming Convention

Overview

This document defines the naming convention for all microservices in the Fengling platform.

URL Structure

{ServicePrefix}/{Version}/{Resource}/{Action}

Components

Component	Description	Examples
ServicePrefix	Unique service identifier	activity, member, order
Version	API version	v1, v2
Resource	Domain entity or resource	campaigns, users, orders
Action	Optional action endpoint	publish, cancel

Service Registry

Service	Prefix	Port	Health Endpoint
Activity	activity	5001	/health
Member	member	5002	/health
Order	order	5003	/health
Payment	payment	5004	/health
RiskControl	risk	5005	/health

Cluster Naming Convention

{ServicePrefix}-service

Examples:

• activity-service
• member-service
• order-service
• payment-service
• risk-service

Gateway Route Configuration

Global Route Pattern

/{ServicePrefix}/{**path} -> {ServicePrefix}-service

Examples

Activity Service:

Route:
  PathPattern: /activity/v1/{**path}
  ClusterId: activity-service

Endpoints:
  GET    /activity/v1/campaigns          # List campaigns
  POST   /activity/v1/campaigns           # Create campaign
  GET    /activity/v1/campaigns/{id}    # Get campaign
  POST   /activity/v1/campaigns/{id}/publish  # Publish campaign

Member Service:

Route:
  PathPattern: /member/v1/{**path}
  ClusterId: member-service

Endpoints:
  GET    /member/v1/users               # List users
  POST   /member/v1/users               # Create user
  GET    /member/v1/users/{id}          # Get user
  PUT    /member/v1/users/{id}          # Update user

Order Service:

Route:
  PathPattern: /order/v1/{**path}
  ClusterId: order-service

Endpoints:
  GET    /order/v1/orders               # List orders
  POST   /order/v1/orders               # Create order
  GET    /order/v1/orders/{id}          # Get order
  PUT    /order/v1/orders/{id}/cancel   # Cancel order

Gateway Registration

Activity Service Registration Script

# Register Activity Service
./scripts/gateway/register-service.sh \
    --service-prefix "activity" \
    --gateway-url "http://localhost:5000" \
    --address "http://localhost:5001"

# After registration, access endpoints at:
# GET http://localhost:5000/activity/v1/campaigns
# POST http://localhost:5000/activity/v1/campaigns

Versioning Strategy

Version Lifecycle

Version	Status	Description
v1	Active	Current stable API
v2	Planning	Next major version
beta	Testing	Beta releases

Versioning Rules

1. Major Version (v1, v2): Breaking changes require version bump
2. Minor Updates: Backward-compatible additions don't require version change
3. Deprecation: Old versions should be supported for at least 6 months

Multi-Tenancy Support

Tenant-Specific Routes

For dedicated tenant instances:

/tenant/{tenantCode}/{ServicePrefix}/{Version}/{**path}

Example:

/tenant/acme/activity/v1/campaigns

Health Check Endpoints

Service	Health Path
Activity	/health
Member	/health
Order	/health
Payment	/health
Risk	/health

Monitoring & Metrics

Service Labels

Label	Value
service	activity
version	v1
tenant	{tenantCode}

Best Practices

1. Consistent Naming

• Use lowercase for all components
• Use hyphens for multi-word names: risk-control NOT riskControl
• Avoid abbreviations: campaigns NOT cmps

2. Resource Naming

• Use plural nouns for collections: campaigns NOT campaignList
• Use singular for single resources: campaign/{id} NOT campaigns/{id}

3. Action Endpoints

• Use HTTP verbs for CRUD: GET, POST, PUT, DELETE
• Use specific verbs for actions: publish, cancel, activate

4. Path Parameters

• Use descriptive names: /campaigns/{campaignId} NOT /campaigns/{id}
• Consistent parameter naming across services

Migration Guide

Updating Existing Routes

Before:

/api/campaigns
/api/orders

After:

/activity/v1/campaigns
/order/v1/orders

Migration Strategy:

1. Register new routes with v1
2. Keep old routes active (alias)
3. Update clients to use new format
4. Remove old routes after transition period