97 lines
3.5 KiB
Plaintext
97 lines
3.5 KiB
Plaintext
---
|
|
alwaysApply: true
|
|
---
|
|
|
|
## 2. Django App (Module) Naming
|
|
|
|
| Item | Convention | Example |
|
|
|--------|------------|----------------------------|
|
|
| App name | snake_case, **بدون** پسوند `_api` | `account`, `auth`, `sensor_hub` |
|
|
|
|
- نام اپها را با `_api` تمام **نکنید**. مثلاً بهجای `account_api` از `account` استفاده کنید.
|
|
- برای ماژولهای فقط API، همان نام دامنه کافی است (مثلاً `auth`، `account`).
|
|
|
|
---
|
|
|
|
## 3. Model and Database Field Naming
|
|
|
|
| Item | Convention | Example |
|
|
|-------------------|-------------------------|----------------------------------------------|
|
|
| Model | PascalCase | `UserProfile` |
|
|
| Fields | snake_case | `first_name`, `email_address` |
|
|
| Boolean | `is_` / `has_` + name | `is_active`, `has_paid` |
|
|
| Date/Time | `created_at` / `updated_at` | `created_at`, `updated_at` |
|
|
| ForeignKey / M2M | snake_case, often model name | `author = ForeignKey(UserProfile)` |
|
|
| Choices / Enum | UPPER_SNAKE_CASE values | `role = CharField(choices=(("ADMIN","Admin"), ("USER","User")))` |
|
|
|
|
---
|
|
|
|
## 4. DRF Conventions
|
|
|
|
- **Serializer:** Validation + data transformation. Use PascalCase names.
|
|
- **Service layer:** All business logic lives here.
|
|
- **View:** Orchestration only — call services and return responses. No business logic in views.
|
|
- **URLs:** Define endpoints only. Use kebab-case for URL paths.
|
|
|
|
---
|
|
|
|
## 5. API Response Format
|
|
|
|
همه پاسخهای API باید فیلد `code` را برگردانند؛ مقدار آن برابر **HTTP status code** درخواست است (مثلاً 200، 201، 400، 404).
|
|
|
|
| فیلد | توضیح |
|
|
|-------|----------------------------------------|
|
|
| `code` | کد وضعیت HTTP (مثلاً 200، 404، 500) |
|
|
| `msg` | پیام (مثلاً "success" برای 2xx) |
|
|
| `data` | دادهٔ برگشتی (اختیاری) |
|
|
|
|
مثال:
|
|
```json
|
|
{"code": 200, "msg": "success", "data": {...}}
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Simple Example: How the Layers Connect (users app)
|
|
|
|
```python
|
|
# models.py
|
|
class UserProfile(models.Model):
|
|
first_name = models.CharField(max_length=50)
|
|
last_name = models.CharField(max_length=50)
|
|
email_address = models.EmailField(unique=True)
|
|
is_active = models.BooleanField(default=True)
|
|
created_at = models.DateTimeField(auto_now_add=True)
|
|
updated_at = models.DateTimeField(auto_now=True)
|
|
|
|
|
|
# serializers.py
|
|
class UserCreateSerializer(serializers.ModelSerializer):
|
|
class Meta:
|
|
model = UserProfile
|
|
fields = ["first_name", "last_name", "email_address"]
|
|
|
|
|
|
# services.py
|
|
def create_user(first_name, last_name, email_address):
|
|
return UserProfile.objects.create(
|
|
first_name=first_name,
|
|
last_name=last_name,
|
|
email_address=email_address,
|
|
)
|
|
|
|
|
|
# views.py
|
|
class UserCreateAPIView(APIView):
|
|
def post(self, request):
|
|
serializer = UserCreateSerializer(data=request.data)
|
|
serializer.is_valid(raise_exception=True)
|
|
user = create_user(**serializer.validated_data)
|
|
return Response({"code": 201, "msg": "success", "data": {"id": user.id}}, status=201)
|
|
```
|
|
|
|
- All names follow the conventions above.
|
|
- Business logic is in `services.py`.
|
|
- Serializer only validates and serializes.
|
|
- View only orchestrates (calls service, returns response).
|