{"id":25824164,"url":"https://github.com/utmhikari/start-fastapi","last_synced_at":"2025-02-28T12:36:40.149Z","repository":{"id":47899223,"uuid":"237467624","full_name":"utmhikari/start-fastapi","owner":"utmhikari","description":"a lightweight web app framework based on fastapi","archived":false,"fork":false,"pushed_at":"2023-02-14T22:22:54.000Z","size":81,"stargazers_count":76,"open_issues_count":1,"forks_count":24,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-07-30T17:00:49.259Z","etag":null,"topics":["asgi","fastapi","python","uvicorn","web-application","web-application-framework","web-development","webapp"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/utmhikari.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-01-31T16:15:32.000Z","updated_at":"2024-07-29T05:37:29.000Z","dependencies_parsed_at":"2022-08-12T14:00:48.307Z","dependency_job_id":null,"html_url":"https://github.com/utmhikari/start-fastapi","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utmhikari%2Fstart-fastapi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utmhikari%2Fstart-fastapi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utmhikari%2Fstart-fastapi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/utmhikari%2Fstart-fastapi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/utmhikari","download_url":"https://codeload.github.com/utmhikari/start-fastapi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241150665,"owners_count":19918354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asgi","fastapi","python","uvicorn","web-application","web-application-framework","web-development","webapp"],"created_at":"2025-02-28T12:36:39.624Z","updated_at":"2025-02-28T12:36:40.142Z","avatar_url":"https://github.com/utmhikari.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# start-fastapi\n\nVersion 2021, based on [FastAPI](https://github.com/tiangolo/fastapi), an easy-to-use web app developed upon [Starlette Framework](https://www.starlette.io/)\n\n- [Version 2020](https://github.com/utmhikari/start-fastapi/tree/v2020_final)\n- [中文文档](./misc/doc/README_CN.md)\n\n## Requirements\n\n- python 3.6+ (for static typing check)\n- `pip3 install -r ./requirements.txt`\n  - fastapi, uvicorn, python-dotenv, python-multipart, websockets, etc\n- idea/pycharm (recommended) + venv\n\n## Structure\n\nThe web application is based on onion style~\n\n![onion](http://www.zyiz.net/upload/202006/15/202006150525428099.png)\n\nThe directory structure is:\n\n- app: logics for your application, includes `__init__.py` as entry of user modules\n  - handler: controllers\n  - middleware: router middleware, like cors\n  - model: basic data models and internal logics\n  - service: external logics (to users)\n- cfg: config of different envs\n  - dev: configs of dev env\n    - app.cfg: [python-dotenv](https://github.com/theskumar/python-dotenv) cfg for fastapi\n    - uvicorn.json: cfg for [uvicorn ASGI server](https://www.uvicorn.org/), the launcher for fastapi\n    - logger.json: [logging cfg](https://github.com/encode/uvicorn/blob/master/uvicorn/config.py) for uvicorn\n  - prod: configs of production env\n- core: low level libraries and logics, includes `__init__.py` as entry of core modules, better make it able to be reused in other projects\n  - handler\n  - lib: shortcut apis for user to build logics\n  - model\n  - service\n    - trans: **transaction service**, for managing tasks running in background\n- misc: misc parts, like build, test scripts, etc\n  - build: build scripts\n  - dev: resources for dev usage\n    - gen_code.py: a script for generating codes\n  - doc: docs\n  - test: test scripts\n- main.py: main entry, init uvicorn and start fastapi app\n- requirements.txt: py package requirements\n\n## Quick Start\n\n### Launch App Server\n\nRun `./main.py` to start the example, which includes:\n\n- core modules: health check handler, basic models, transaction service\n- [cors](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) middleware configured with wildcard *\n- test handlers, models and service: simulates a simple market trade system with products and customers\n  - examples of websocket and upload file are also included in test handlers\n\nThe internal steps are:\n\n- `./main.py` loads the configs inside `./cfg/{env}` on cmd args, then calls `uvicorn.run` to start fastapi app at `./app/__init__.py`\n- in `./app/__init__.py`, core modules and user handlers/models/services are loaded at `startup` event of fastapi app\n\nYou can put your launch scripts inside `./misc/build` for your different launch options\n\n### Coding Guide\n\nTo build your logic, common steps are follows:\n\n- `./main.py` runs server in dev environment in default, in which hot-reload is enabled\n- add handlers in `./app/handler`, add corresponding `import` \u0026 `APP.include_router` codes in `./app/__init__.py`\n- add data models in `./app/model`, add services in `./app/service`\n- add [middlewares](https://fastapi.tiangolo.com/tutorial/middleware/) in `./app/middleware` if necessary\n\nSome tips for coding:\n\n- GET `/docs` to test the routers on web page\n- Avoid using coroutines (`async def` functions), as it may block the main evtloop, so that other requests are not handled in time. `def` functions will be invoked in different threads\n- codes of `./core` should be shareable (for other projects), codes of `./app` should fit with current project\n- You can use `./misc/dev/gen_code.py` to generate template codes for handlers, models \u0026 services. Exec it with working directory as project root directory\n- Code models based on `pydantic.BaseModel`, it's powerful\n\n### HTTP Response\n\nMost of the handled requests should contain a status code of 200\n\nA simple solution is to use `Resp` model in `./core/model/handler.py` to generate response body for your handlers\n\n```text\n{\n  \"success\": bool,\n  \"message\": str,\n  \"code\": IntEnum,\n  \"data\": Any,\n}\n```\n\nUse `Resp.ok` to generate success response and use `Resp.err` to generate error response\n\n## Misc\n\n### WebSocket\n\nThe test handler `./app/handler/test.py` contains ws handler examples\n\nTo know more about it, see [websocket documentation](https://fastapi.tiangolo.com/advanced/websockets/)\n\n### Deployment\n\nRun `./misc/build/pack.sh` to pack the project into `./misc/build/start-fastapi.tar.gz`\n\nSee `./misc/build/Dockerfile` for an example of [docker deployment](https://docs.docker.com/engine/reference/builder/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futmhikari%2Fstart-fastapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Futmhikari%2Fstart-fastapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Futmhikari%2Fstart-fastapi/lists"}