forked from mengyxu/noob-components
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
72 lines
2.0 KiB
72 lines
2.0 KiB
3 months ago
|
# Plugs API Guidelines
|
||
|
|
|
||
|
|
> Typed API functions wrapping HTTP calls.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Overview
|
||
|
|
|
||
|
|
This directory documents the API layer in `plugs/api/`.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Guidelines Index
|
||
|
|
|
||
|
|
| Guide | Description | Status |
|
||
|
|
|-------|-------------|--------|
|
||
|
|
| [base](./base.md) | Base API utilities | Filled |
|
||
|
|
| [user](./user.md) | User API | Filled |
|
||
|
|
| [role](./role.md) | Role API | Filled |
|
||
|
|
| [permission](./permission.md) | Permission API | Filled |
|
||
|
|
| [dictionary](./dictionary.md) | Dictionary API | Filled |
|
||
|
|
| [config](./config.md) | Config API | Filled |
|
||
|
|
| [log](./log.md) | Log API | Filled |
|
||
|
|
| [public](./public.md) | Public API | Filled |
|
||
|
|
| [buffer](./buffer.md) | Buffer API | Filled |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Common Patterns
|
||
|
|
|
||
|
|
### HTTP Methods
|
||
|
|
|
||
|
|
| Method | Function | Purpose |
|
||
|
|
|--------|----------|---------|
|
||
|
|
| GET | `get`, `queryPage`, `queryList` | Read operations |
|
||
|
|
| POST | `save`, `add` | Create operations |
|
||
|
|
| PUT | `update`, `set` | Update operations |
|
||
|
|
| DELETE | `deleteById`, `del`, `clean` | Delete operations |
|
||
|
|
|
||
|
|
### Response Handling
|
||
|
|
|
||
|
|
All API functions return `Promise` and handle errors by resolving with falsy values instead of rejecting:
|
||
|
|
- `resolve(false)` - Operation failed
|
||
|
|
- `resolve([])` - List/query returned nothing
|
||
|
|
- `resolve({})` - Get by ID returned nothing
|
||
|
|
|
||
|
|
### URL Patterns
|
||
|
|
|
||
|
|
- **Standard**: `resource` (e.g., `user`, `role`, `permission`)
|
||
|
|
- **Public**: `public/resource` (no auth required)
|
||
|
|
- **With ID**: `resource/id` (get, update, delete single item)
|
||
|
|
|
||
|
|
### Function Naming
|
||
|
|
|
||
|
|
| Pattern | Example | Description |
|
||
|
|
|---------|---------|-------------|
|
||
|
|
| `list(example?)` | `role.list({ status: 1 })` | List with optional filter |
|
||
|
|
| `add(item)` | `user.add({ username: 'x' })` | Create new |
|
||
|
|
| `set(item)` | `config.set({ key: 'x', value: 'y' })` | Update existing |
|
||
|
|
| `del(item)` | `role.del({ roleCode: 'ADMIN' })` | Delete (passes ID field) |
|
||
|
|
| `getValue(key)` | `config.getValue('app.name')` | Get single value |
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## HTTP Layer
|
||
|
|
|
||
|
|
See `plugs/http/axios.ts` for the underlying HTTP client configuration.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
**Language**: English
|