FastAPI-Nacos-Extension

中文说明 · Documentation · Changelog

fastapi-nacos-extension 0.1.1 is a typed, production-oriented FastAPI integration for Nacos 2.x. It provides process-safe service registration, discovery, raw configuration reads, local health status, bounded shutdown deregistration and post-fork recovery. Async methods keep SDK work off the ASGI event loop, while matching _sync methods support synchronous callers.

The distribution name is fastapi-nacos-extension and the import package is fastapi_nacos_extension. This project is unrelated to the existing public PyPI distribution named fastapi-nacos.

Compatibility

• Python 3.8 or newer
• FastAPI >=0.112.2,<1.0.0; Python 3.8 resolves at most 0.124.4
• nacos-sdk-python 2.0.0 through 2.0.11 (>=2.0.0,<3.0.0)
• Nacos server 2.3.2

Installation

From PyPI after the first public release:

python -m pip install fastapi-nacos-extension

From a built wheel:

python -m pip install ./fastapi_nacos_extension-0.1.1-py3-none-any.whl

From a local checkout:

python -m pip install .

Quick start

from fastapi import FastAPI
from fastapi_nacos_extension import FastAPINacos

app = FastAPI()
nacos = FastAPINacos(
    app,
    {
        "NACOS_SERVER_ADDR": "127.0.0.1:8848",
        "NACOS_SERVICE_NAME": "orders-api",
        "NACOS_SERVICE_IP": "127.0.0.1",
        "NACOS_SERVICE_PORT": 8000,
        "NACOS_AUTO_REGISTER": True,
        "NACOS_HEALTH_CHECK_ENABLED": True,
    },
)


@app.get("/upstream")
async def upstream():
    return await nacos.get_one_healthy_instance(app, "payments-api", strategy="weight")


@app.get("/upstream-sync")
def upstream_sync():
    return nacos.get_one_healthy_instance_sync(app, "payments-api", strategy="weight")


@app.get("/remote-config")
async def remote_config():
    return {"content": await nacos.get_config(app, "orders.yaml")}

Run it with uvicorn app:app --host 0.0.0.0 --port 8000. Initialization is local and lazy: no Nacos client is constructed and no network request is made until application startup or the first explicit operation.

Public API

All application-scoped operations take an explicit FastAPI instance. Choose the async API in an async context so SDK work runs in a worker thread, or the corresponding _sync API in synchronous code to run it in the calling thread.

FastAPINacos(app=None, config=None)
init_app(app, config=None)
await register_instance(app)
register_instance_sync(app)
await deregister_instance(app)
deregister_instance_sync(app)
await get_client(app)
get_client_sync(app)
get_cached_client(app)
get_config_snapshot(app)
await list_instances(app, service_name, group=None, healthy_only=True,
                     cluster=None, metadata=None)
list_instances_sync(app, service_name, group=None, healthy_only=True,
                    cluster=None, metadata=None)
await get_one_healthy_instance(app, service_name, group=None, strategy=None,
                               cluster=None, metadata=None)
get_one_healthy_instance_sync(app, service_name, group=None, strategy=None,
                              cluster=None, metadata=None)
normalize_instance(instance)
await get_config(app, data_id=None, group=None)
get_config_sync(app, data_id=None, group=None)
get_status(app)

get_status() is a local-only, side-effect-free 16-field lifecycle snapshot. When enabled, GET /health/nacos exposes a stable seven-field local health response and never contacts Nacos.

Design guarantees

• Configuration precedence is defaults, constructor config, then init_app() config.
• Each application and PID owns an isolated runtime and defensive config snapshot.
• Repeated initialization by the same extension is idempotent.
• User lifespan handlers are composed with the plugin lifespan.
• Registration is non-blocking and uses a last-command-wins state machine.
• Only one lifecycle worker and one Naming RPC run per application/PID.
• Successful registration identity is cached for exact deregistration.
• Transient transport failures recover at a low frequency; deterministic failures stop.
• Preload/fork workers rebuild locks, client and runtime state in the child process.
• Raw SDK logs are silenced because they can contain credentials or config content.

Documentation

• Quick start
• Configuration
• API reference
• Registration
• Discovery
• Configuration center
• Health check
• Production
• Troubleshooting
• Compatibility
• Release process

Development

Use the repository environment and run the complete gate:

.venv/Scripts/python -m ruff check fastapi_nacos_extension tests examples scripts
.venv/Scripts/python -m mypy fastapi_nacos_extension
.venv/Scripts/python -m pytest
.venv/Scripts/python -m build
.venv/Scripts/python -m twine check dist/*

CI additionally verifies every Python minor from 3.8 through 3.14. FastAPI boundary releases and the latest tested version, 0.141.1, are selected according to each interpreter's supported range. See the compatibility guide for the complete matrix.

Integration tests are opt-in and must use a disposable Nacos 2.3.2 instance:

docker compose -f examples/docker-compose-nacos.yml up -d
NACOS_INTEGRATION=1 .venv/Scripts/python -m pytest -m integration

License and provenance

The repository is licensed under Apache License 2.0. Portions are adapted from an Apache-2.0-licensed predecessor; see NOTICE for attribution and scope.